tasslihorec sfaxoistadet bintestcss PKO\ 0 shadow.3.gznu[Xko#.k][}4N@k+ MQH9 =^;6v >="?l.Rsݼz %}%t"- ȃRJ8:1;c>?&g4qB\Jgie(mn};WI٬עb/u^h/#:ΕXBREWR_%SW7qL NozJ[ŏ[u[M[zo![+;t"3p[Tʉ*[u>˞~'XOu9b3բzMBYg{ ú\d?wˢL!샯] =R%iRK+uU'y'=H+2p Y^'1JÇ,Io~U/n]6U>qdv[]7)d$ A`G;+R΢l%/ZHߏF|=mLSQk #R[?}[*Oͺ-{+|Z'Q{`1Ad)*}rI-,|ɱK۳) MJyBV){&#M_f^!EQf҉mcŎ-BFPE $?(+uRK'= u/^@.A(1#ZKJ*֖lEQkr|Q7s'J^yUǠ^j+CITUlc*-[$)b<ZՍVkhmDVcjU98WV52u'QF1MJkJKunŌ0|{oj{֝{Kx좶BFl$6hf,qVo_Ui*#h&B`\|q ucu, 횃*QDžY""ˬ].h,mN#kDYX2H7a(maM>is\.h$C\aO·E`ۈ/Yx5nGhEe&:vqk5fo*{8h\ 嚼S=IT P$q wP[{AhRvFd97.8Ɂyd6q?_Lal͙e3bi@CĐJֶW~0! [Ux6 RCUJl [jsm-D/PD ƶ#[ dSǏɸ<8N̼-5yP%Be7gmy;m= A]==ڈl3Ф"P.EG <2mG;4:KΞwM%/B"PK@O\$m6m6 version.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "version 3" .TH version 3 "2022-07-15" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" version \- Perl extension for Version Objects .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& # 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"); # deprecated \& use version; our $VERSION = qv("v1.2_3"); # deprecated \& \& # 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; .Ve .SH "DESCRIPTION" .IX Header "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 \s-1API\s0 for all versions of Perl. All previous releases before 0.74 are deprecated and should not be used due to incompatible \s-1API\s0 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. .PP .Vb 1 \& use version 0.77; # even for Perl v.5.10.0 .Ve .SH "TYPES OF VERSION OBJECTS" .IX Header "TYPES OF VERSION OBJECTS" There are two different types of version objects, corresponding to the two different styles of versions in use: .IP "Decimal Versions" 2 .IX Item "Decimal Versions" The classic floating-point number \f(CW$VERSION\fR. 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 (\*(L"1.50\*(R") are preserved in any warnings or other output. .IP "Dotted Decimal Versions" 2 .IX 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"\fBis_strict()\fR\*(R" test. .SH "DECLARING VERSIONS" .IX Header "DECLARING VERSIONS" If you have a module that uses a decimal \f(CW$VERSION\fR (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 \f(CW$VERSION\fR assignment: .PP .Vb 1 \& our $VERSION = "1.02"; .Ve .PP Since Perl v5.10.0 includes the version.pm comparison logic anyways, you don't need to do anything at all. .SS "How to convert a module from decimal to dotted-decimal" .IX Subsection "How to convert a module from decimal to dotted-decimal" If you have used a decimal \f(CW$VERSION\fR in the past and wish to switch to a dotted-decimal \f(CW$VERSION\fR, then you need to make a one-time conversion to the new format. .PP \&\fBImportant Note\fR: you must ensure that your new \f(CW$VERSION\fR is numerically greater than your current decimal \f(CW$VERSION\fR; this is not always obvious. First, convert your old decimal version (e.g. 1.02) to a normalized dotted-decimal form: .PP .Vb 2 \& $ perl \-Mversion \-e \*(Aqprint version\->parse("1.02")\->normal\*(Aq \& v1.20.0 .Ve .PP Then increment any of the dotted-decimal components (v1.20.1 or v1.21.0). .ie n .SS "How to ""declare()"" a dotted-decimal version" .el .SS "How to \f(CWdeclare()\fP a dotted-decimal version" .IX Subsection "How to declare() a dotted-decimal version" .Vb 1 \& use version; our $VERSION = version\->declare("v1.2.3"); .Ve .PP The \f(CW\*(C`declare()\*(C'\fR method always creates dotted-decimal version objects. When used in a module, you \fBmust\fR put it on the same line as \*(L"use version\*(R" to ensure that \f(CW$VERSION\fR is read correctly by \s-1PAUSE\s0 and installer tools. You should also add 'version' to the 'configure_requires' section of your module metadata file. See instructions in ExtUtils::MakeMaker or Module::Build for details. .PP \&\fBImportant Note\fR: Even if you pass in what looks like a decimal number (\*(L"1.2\*(R"), a dotted-decimal will be created (\*(L"v1.200.0\*(R"). To avoid confusion or unintentional errors on older Perls, follow these guidelines: .IP "\(bu" 2 Always use a dotted-decimal with (at least) three components .IP "\(bu" 2 Always use a leading-v .IP "\(bu" 2 Always quote the version .PP If you really insist on using version.pm with an ordinary decimal version, use \f(CW\*(C`parse()\*(C'\fR instead of declare. See the \*(L"\s-1PARSING AND COMPARING VERSIONS\*(R"\s0 for details. .PP See also version::Internals for more on version number conversion, quoting, calculated version numbers and declaring developer or \*(L"alpha\*(R" version numbers. .SH "PARSING AND COMPARING VERSIONS" .IX Header "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. .ie n .SS "How to ""parse()"" a version" .el .SS "How to \f(CWparse()\fP a version" .IX Subsection "How to parse() a version" The \f(CW\*(C`parse()\*(C'\fR method takes in anything that might be a version and returns a corresponding version object, doing any necessary conversion along the way. .IP "\(bu" 2 Dotted-decimal: bare v\-strings (v1.2.3) and strings with more than one decimal point and a leading 'v' (\*(L"v1.2.3\*(R"); \s-1NOTE\s0 you can technically use a v\-string or strings with a leading-v and only one decimal point (v1.2 or \&\*(L"v1.2\*(R"), but you will confuse both yourself and others. .IP "\(bu" 2 Decimal: regular decimal numbers (literal or in a string) .PP Some examples: .PP .Vb 8 \& $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 .Ve .PP See version::Internals for more on version number conversion. .SS "How to check for a legal version string" .IX Subsection "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: .ie n .IP """is_lax()""" 4 .el .IP "\f(CWis_lax()\fR" 4 .IX Item "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: .Sp .Vb 5 \& v1.2 \& 1.2345.6 \& v1.23_4 \& 1.2345 \& 1.2345_01 .Ve .ie n .IP """is_strict()""" 4 .el .IP "\f(CWis_strict()\fR" 4 .IX Item "is_strict()" If you want to limit yourself to a much more narrow definition of what a version string constitutes, \f(CW\*(C`is_strict()\*(C'\fR is limited to version strings like the following list: .Sp .Vb 2 \& v1.234.5 \& 2.3456 .Ve .PP See 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 \f(CW\*(C`is_lax()\*(C'\fR and \&\f(CW\*(C`is_strict()\*(C'\fR are not sufficient for your needs. .SS "How to compare version objects" .IX Subsection "How to compare version objects" Version objects overload the \f(CW\*(C`cmp\*(C'\fR and \f(CW\*(C`<=>\*(C'\fR operators. Perl automatically generates all of the other comparison operators based on those two so all the normal logical comparisons will work. .PP .Vb 3 \& if ( version\->parse($v1) == version\->parse($v2) ) { \& # do stuff \& } .Ve .PP If a version object is compared against a non-version object, the non-object term will be converted to a version object using \f(CW\*(C`parse()\*(C'\fR. This may give surprising results: .PP .Vb 2 \& $v1 = version\->parse("v0.95.0"); \& $bool = $v1 < 0.94; # TRUE since 0.94 is v0.940.0 .Ve .PP Always comparing to a version object will help avoid surprises: .PP .Vb 1 \& $bool = $v1 < version\->parse("v0.94.0"); # FALSE .Ve .PP Note that \*(L"alpha\*(R" version objects (where the version string contains a trailing underscore segment) compare as less than the equivalent version without an underscore: .PP .Vb 1 \& $bool = version\->parse("1.23_45") < version\->parse("1.2345"); # TRUE .Ve .PP See version::Internals for more details on \*(L"alpha\*(R" versions. .SH "OBJECT METHODS" .IX Header "OBJECT METHODS" .SS "\fBis_alpha()\fP" .IX Subsection "is_alpha()" True if and only if the version object was created with a underscore, e.g. .PP .Vb 2 \& version\->parse(\*(Aq1.002_03\*(Aq)\->is_alpha; # TRUE \& version\->declare(\*(Aq1.2.3_4\*(Aq)\->is_alpha; # TRUE .Ve .SS "\fBis_qv()\fP" .IX Subsection "is_qv()" True only if the version object is a dotted-decimal version, e.g. .PP .Vb 4 \& version\->parse(\*(Aqv1.2.0\*(Aq)\->is_qv; # TRUE \& version\->declare(\*(Aqv1.2\*(Aq)\->is_qv; # TRUE \& qv(\*(Aq1.2\*(Aq)\->is_qv; # TRUE \& version\->parse(\*(Aq1.2\*(Aq)\->is_qv; # FALSE .Ve .SS "\fBnormal()\fP" .IX Subsection "normal()" Returns a string with a standard 'normalized' dotted-decimal form with a leading-v and at least 3 components. .PP .Vb 2 \& version\->declare(\*(Aqv1.2\*(Aq)\->normal; # v1.2.0 \& version\->parse(\*(Aq1.2\*(Aq)\->normal; # v1.200.0 .Ve .SS "\fBnumify()\fP" .IX Subsection "numify()" Returns a value representing the object in a pure decimal. .PP .Vb 2 \& version\->declare(\*(Aqv1.2\*(Aq)\->numify; # 1.002000 \& version\->parse(\*(Aq1.2\*(Aq)\->numify; # 1.200 .Ve .SS "\fBstringify()\fP" .IX Subsection "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. .PP .Vb 3 \& version\->declare(\*(Aqv1.2\*(Aq)\->stringify; # v1.2 \& version\->parse(\*(Aq1.200\*(Aq)\->stringify; # 1.2 \& version\->parse(1.02_30)\->stringify; # 1.023 .Ve .SH "EXPORTED FUNCTIONS" .IX Header "EXPORTED FUNCTIONS" .SS "\fBqv()\fP" .IX Subsection "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: .PP .Vb 1 \& use version 0.77 (); .Ve .SS "\fBis_lax()\fP" .IX Subsection "is_lax()" (Not exported by default) .PP This function takes a scalar argument and returns a boolean value indicating whether the argument meets the \*(L"lax\*(R" rules for a version number. Leading and trailing spaces are not allowed. .SS "\fBis_strict()\fP" .IX Subsection "is_strict()" (Not exported by default) .PP This function takes a scalar argument and returns a boolean value indicating whether the argument meets the \*(L"strict\*(R" rules for a version number. Leading and trailing spaces are not allowed. .SH "AUTHOR" .IX Header "AUTHOR" John Peacock .SH "SEE ALSO" .IX Header "SEE ALSO" version::Internals. .PP perl. PK@O\uTf f CPAN::Queue.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::Queue 3" .TH CPAN::Queue 3 "2020-05-19" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::Queue \- internal queue support for CPAN.pm .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK@O\ IO::Tty.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Tty 3" .TH Tty 3 "2023-12-28" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" IO::Tty \- Low\-level allocate a pseudo\-Tty, import constants. .SH "VERSION" .IX Header "VERSION" 1.20 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& use IO::Tty qw(TIOCNOTTY); \& ... \& # use only to import constants, see IO::Pty to create ptys. .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`IO::Tty\*(C'\fR is used internally by \f(CW\*(C`IO::Pty\*(C'\fR to create a pseudo-tty. You wouldn't want to use it directly except to import constants, use \&\f(CW\*(C`IO::Pty\*(C'\fR. For a list of importable constants, see IO::Tty::Constant. .PP Windows is now supported, but \s-1ONLY\s0 under the Cygwin environment, see . .PP Please note that pty creation is very system-dependend. From my experience, any modern \s-1POSIX\s0 system should be fine. Find below a list of systems that \f(CW\*(C`IO::Tty\*(C'\fR should work on. A more detailed table (which is slowly getting out-of-date) is available from the project pages document manager at SourceForge . .PP If you have problems on your system and your system is listed in the \&\*(L"verified\*(R" list, you probably have some non-standard setup, e.g. you compiled your Linux-kernel yourself and disabled ptys (bummer!). Please ask your friendly sysadmin for help. .PP If your system is not listed, unpack the latest version of \f(CW\*(C`IO::Tty\*(C'\fR, do a \f(CW\*(Aqperl Makefile.PL; make; make test; uname \-a\*(Aq\fR and send me (\fIRGiersig@cpan.org\fR) the results and I'll see what I can deduce from that. There are chances that it will work right out-of-the-box... .PP If it's working on your system, please send me a short note with details (version number, distribution, etc. 'uname \-a' and 'perl \-V' is a good start; also, the output from \*(L"perl Makefile.PL\*(R" contains a lot of interesting info, so please include that as well) so I can get an overview. Thanks! .SH "VERIFIED SYSTEMS, KNOWN ISSUES" .IX Header "VERIFIED SYSTEMS, KNOWN ISSUES" This is a list of systems that \f(CW\*(C`IO::Tty\*(C'\fR seems to work on ('make test' passes) with comments about \*(L"features\*(R": .IP "\(bu" 4 \&\s-1AIX 4.3\s0 .Sp Returns \s-1EIO\s0 instead of \s-1EOF\s0 when the slave is closed. Benign. .IP "\(bu" 4 \&\s-1AIX 5\s0.x .IP "\(bu" 4 FreeBSD 4.4 .Sp \&\s-1EOF\s0 on the slave tty is not reported back to the master. .IP "\(bu" 4 OpenBSD 2.8 .Sp The ioctl \s-1TIOCSCTTY\s0 sometimes fails. This is also known in Tcl/Expect, see http://expect.nist.gov/FAQ.html .Sp \&\s-1EOF\s0 on the slave tty is not reported back to the master. .IP "\(bu" 4 Darwin 7.9.0 .IP "\(bu" 4 \&\s-1HPUX 10.20 & 11.00\s0 .Sp \&\s-1EOF\s0 on the slave tty is not reported back to the master. .IP "\(bu" 4 \&\s-1IRIX 6.5\s0 .IP "\(bu" 4 Linux 2.2.x & 2.4.x .Sp Returns \s-1EIO\s0 instead of \s-1EOF\s0 when the slave is closed. Benign. .IP "\(bu" 4 \&\s-1OSF 4.0\s0 .Sp \&\s-1EOF\s0 on the slave tty is not reported back to the master. .IP "\(bu" 4 Solaris 8, 2.7, 2.6 .Sp Has the \*(L"feature\*(R" of returning \s-1EOF\s0 just once?! .Sp \&\s-1EOF\s0 on the slave tty is not reported back to the master. .IP "\(bu" 4 Windows NT/2k/XP (under Cygwin) .Sp When you send (print) a too long line (>160 chars) to a non-raw pty, the call just hangs forever and even \fBalarm()\fR cannot get you out. Don't complain to me... .Sp \&\s-1EOF\s0 on the slave tty is not reported back to the master. .IP "\(bu" 4 z/OS .PP The following systems have not been verified yet for this version, but a previous version worked on them: .IP "\(bu" 4 \&\s-1SCO\s0 Unix .IP "\(bu" 4 NetBSD .Sp probably the same as the other *BSDs... .PP If you have additions to these lists, please mail them to <\fIRGiersig@cpan.org\fR>. .SH "SEE ALSO" .IX Header "SEE ALSO" IO::Pty, IO::Tty::Constant .SH "MAILING LISTS" .IX Header "MAILING LISTS" As this module is mainly used by Expect, support for it is available via the two Expect mailing lists, expectperl-announce and expectperl-discuss, at .PP .Vb 1 \& http://lists.sourceforge.net/lists/listinfo/expectperl\-announce .Ve .PP and .PP .Vb 1 \& http://lists.sourceforge.net/lists/listinfo/expectperl\-discuss .Ve .SH "AUTHORS" .IX Header "AUTHORS" Originally by Graham Barr <\fIgbarr@pobox.com\fR>, based on the Ptty module by Nick Ing-Simmons <\fInik@tiuk.ti.com\fR>. .PP Now maintained and heavily rewritten by Roland Giersig <\fIRGiersig@cpan.org\fR>. .PP Contains copyrighted stuff from openssh v3.0p1, authored by Tatu Ylonen , Markus Friedl and Todd C. Miller . I also got a lot of inspiration from the pty code in Xemacs. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Now all code is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP Nevertheless the above \s-1AUTHORS\s0 retain their copyrights to the various parts and want to receive credit if their source code is used. See the source for details. .SH "DISCLAIMER" .IX Header "DISCLAIMER" \&\s-1THIS SOFTWARE IS PROVIDED\s0 ``\s-1AS IS\s0'' \s-1AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\s0 .PP In other words: Use at your own risk. Provided as is. Your mileage may vary. Read the source, Luke! .PP And finally, just to be sure: .PP Any Use of This Product, in Any Manner Whatsoever, Will Increase the Amount of Disorder in the Universe. Although No Liability Is Implied Herein, the Consumer Is Warned That This Process Will Ultimately Lead to the Heat Death of the Universe. PK@O\IyGLWP::Protocol::https.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "LWP::Protocol::https 3" .TH LWP::Protocol::https 3 "2024-03-11" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" LWP::Protocol::https \- Provide https support for LWP::UserAgent .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use LWP::UserAgent; \& \& $ua = LWP::UserAgent\->new(ssl_opts => { verify_hostname => 1 }); \& $res = $ua\->get("https://www.example.com"); \& \& # specify a CA path \& $ua = LWP::UserAgent\->new( \& ssl_opts => { \& SSL_ca_path => \*(Aq/etc/ssl/certs\*(Aq, \& verify_hostname => 1, \& } \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The LWP::Protocol::https module provides support for using https schemed URLs with \s-1LWP.\s0 This module is a plug-in to the \s-1LWP\s0 protocol handling, so you don't use it directly. Once the module is installed \s-1LWP\s0 is able to access sites using \s-1HTTP\s0 over \s-1SSL/TLS.\s0 .PP If hostname verification is requested by LWP::UserAgent's \f(CW\*(C`ssl_opts\*(C'\fR, and neither \f(CW\*(C`SSL_ca_file\*(C'\fR nor \f(CW\*(C`SSL_ca_path\*(C'\fR is set, then \f(CW\*(C`SSL_ca_file\*(C'\fR is implied to be the one provided by Mozilla::CA. If the Mozilla::CA module isn't available \s-1SSL\s0 requests will fail. Either install this module, set up an alternative \f(CW\*(C`SSL_ca_file\*(C'\fR or disable hostname verification. .PP This module used to be bundled with the libwww-perl, but it was unbundled in v6.02 in order to be able to declare its dependencies properly for the \s-1CPAN\s0 tool-chain. Applications that need https support can just declare their dependency on LWP::Protocol::https and will no longer need to know what underlying modules to install. .SH "SEE ALSO" .IX Header "SEE ALSO" IO::Socket::SSL, Crypt::SSLeay, Mozilla::CA .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright (c) 1997\-2011 Gisle Aas. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK@O\I*I*YAML::Syck.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "YAML::Syck 3" .TH YAML::Syck 3 "2020-10-26" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" YAML::Syck \- Fast, lightweight YAML loader and dumper .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use YAML::Syck; \& \& # Set this for interoperability with other YAML/Syck bindings: \& # e.g. Load(\*(AqYes\*(Aq) becomes 1 and Load(\*(AqNo\*(Aq) becomes \*(Aq\*(Aq. \& $YAML::Syck::ImplicitTyping = 1; \& \& $data = Load($yaml); \& $yaml = Dump($data); \& \& # $file can be an IO object, or a filename \& $data = LoadFile($file); \& DumpFile($file, $data); \& \& # A string with multiple YAML streams in it \& $yaml = Dump(@data); \& @data = Load($yaml); \& \& # Dumping into a pre\-existing output buffer \& my $yaml; \& DumpInto(\e$yaml, @data); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides a Perl interface to the \fBlibsyck\fR data serialization library. It exports the \f(CW\*(C`Dump\*(C'\fR and \f(CW\*(C`Load\*(C'\fR functions for converting Perl data structures to \s-1YAML\s0 strings, and the other way around. .PP \&\fB\s-1NOTE\s0\fR: If you are working with other language's YAML/Syck bindings (such as Ruby), please set \f(CW$YAML::Syck::ImplicitTyping\fR to \f(CW1\fR before calling the \f(CW\*(C`Load\*(C'\fR/\f(CW\*(C`Dump\*(C'\fR functions. The default setting is for preserving backward-compatibility with \f(CW\*(C`YAML.pm\*(C'\fR. .SH "Differences Between YAML::Syck and YAML" .IX Header "Differences Between YAML::Syck and YAML" .SS "Error handling" .IX Subsection "Error handling" Some calls are designed to die rather than returning \s-1YAML.\s0 You should wrap your calls in eval to assure you do not get unexpected results. .SH "FLAGS" .IX Header "FLAGS" .ie n .SS "$YAML::Syck::Headless" .el .SS "\f(CW$YAML::Syck::Headless\fP" .IX Subsection "$YAML::Syck::Headless" Defaults to false. Setting this to a true value will make \f(CW\*(C`Dump\*(C'\fR omit the leading \f(CW\*(C`\-\-\-\en\*(C'\fR marker. .ie n .SS "$YAML::Syck::SortKeys" .el .SS "\f(CW$YAML::Syck::SortKeys\fP" .IX Subsection "$YAML::Syck::SortKeys" Defaults to false. Setting this to a true value will make \f(CW\*(C`Dump\*(C'\fR sort hash keys. .ie n .SS "$YAML::Syck::SingleQuote" .el .SS "\f(CW$YAML::Syck::SingleQuote\fP" .IX Subsection "$YAML::Syck::SingleQuote" Defaults to false. Setting this to a true value will make \f(CW\*(C`Dump\*(C'\fR always emit single quotes instead of bare strings. .ie n .SS "$YAML::Syck::ImplicitTyping" .el .SS "\f(CW$YAML::Syck::ImplicitTyping\fP" .IX Subsection "$YAML::Syck::ImplicitTyping" Defaults to false. Setting this to a true value will make \f(CW\*(C`Load\*(C'\fR recognize various implicit types in \s-1YAML,\s0 such as unquoted \f(CW\*(C`true\*(C'\fR, \f(CW\*(C`false\*(C'\fR, as well as integers and floating-point numbers. Otherwise, only \f(CW\*(C`~\*(C'\fR is recognized to be \f(CW\*(C`undef\*(C'\fR. .ie n .SS "$YAML::Syck::ImplicitUnicode" .el .SS "\f(CW$YAML::Syck::ImplicitUnicode\fP" .IX Subsection "$YAML::Syck::ImplicitUnicode" Defaults to false. For Perl 5.8.0 or later, setting this to a true value will make \f(CW\*(C`Load\*(C'\fR set Unicode flag on for every string that contains valid \s-1UTF8\s0 sequences, and make \f(CW\*(C`Dump\*(C'\fR return a unicode string. .PP Regardless of this flag, Unicode strings are dumped verbatim without escaping; byte strings with high-bit set will be dumped with backslash escaping. .PP However, because \s-1YAML\s0 does not distinguish between these two kinds of strings, so this flag will affect loading of both variants of strings. .PP If you want to use LoadFile or DumpFile with unicode, you are required to open your own file in order to assure it's \s-1UTF8\s0 encoded: .PP .Vb 2 \& open(my $fh, ">:encoding(UTF\-8)", "out.yml"); \& DumpFile($fh, $hashref); .Ve .ie n .SS "$YAML::Syck::ImplicitBinary" .el .SS "\f(CW$YAML::Syck::ImplicitBinary\fP" .IX Subsection "$YAML::Syck::ImplicitBinary" Defaults to false. For Perl 5.8.0 or later, setting this to a true value will make \f(CW\*(C`Dump\*(C'\fR generate Base64\-encoded \f(CW\*(C`!!binary\*(C'\fR data for all non-Unicode scalars containing high-bit bytes. .ie n .SS "$YAML::Syck::UseCode / $YAML::Syck::LoadCode / $YAML::Syck::DumpCode" .el .SS "\f(CW$YAML::Syck::UseCode\fP / \f(CW$YAML::Syck::LoadCode\fP / \f(CW$YAML::Syck::DumpCode\fP" .IX Subsection "$YAML::Syck::UseCode / $YAML::Syck::LoadCode / $YAML::Syck::DumpCode" These flags control whether or not to try and eval/deparse perl source code; each of them defaults to false. .PP Setting \f(CW$YAML::Syck::UseCode\fR to a true value is equivalent to setting both \f(CW$YAML::Syck::LoadCode\fR and \f(CW$YAML::Syck::DumpCode\fR to true. .ie n .SS "$YAML::Syck::LoadBlessed" .el .SS "\f(CW$YAML::Syck::LoadBlessed\fP" .IX Subsection "$YAML::Syck::LoadBlessed" Defaults to false. Setting to true will allow YAML::Syck to bless objects as it imports objects. This default changed in 1.32. .PP You can create any kind of object with \s-1YAML.\s0 The creation itself is not the critical part. If the class has a \s-1DESTROY\s0 method, it will be called once the object is deleted. An example with File::Temp removing files can be found at .SH "BUGS" .IX Header "BUGS" Dumping Glob/IO values do not work yet. .PP Dumping of Tied variables is unsupported. .PP Dumping into tied (or other magic variables) with \f(CW\*(C`DumpInto\*(C'\fR might not work properly in all cases. .SH "CAVEATS" .IX Header "CAVEATS" This module implements the \s-1YAML 1.0\s0 spec. To deal with data in \s-1YAML 1.1,\s0 please use the \f(CW\*(C`YAML::XS\*(C'\fR module instead. .PP The current implementation bundles libsyck source code; if your system has a site-wide shared libsyck, it will \fInot\fR be used. .PP Tag names such as \f(CW\*(C`!!perl/hash:Foo\*(C'\fR is blessed into the package \f(CW\*(C`Foo\*(C'\fR, but the \f(CW\*(C`!hs/foo\*(C'\fR and \f(CW\*(C`!!hs/Foo\*(C'\fR tags are blessed into \f(CW\*(C`hs::Foo\*(C'\fR. Note that this holds true even if the tag contains non-word characters; for example, \&\f(CW\*(C`!haskell.org/Foo\*(C'\fR is blessed into \f(CW\*(C`haskell.org::Foo\*(C'\fR. Please use Class::Rebless to cast it into other user-defined packages. You can also set the LoadBlessed flag false to disable all blessing. .PP This module has a lot of known issues and has only been semi-actively maintained since 2007. If you encounter an issue with it probably won't be fixed unless you offer up a patch in Git that's ready for release. .PP There are still good reasons to use this module, such as better interoperability with other syck wrappers (like Ruby's), or some edge case of \s-1YAML\s0's syntax that it handles better. It'll probably work perfectly for you, but if it doesn't you may want to look at \&\s-1YAML::XS\s0, or perhaps at looking another serialization format like \&\s-1JSON\s0. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1YAML\s0, JSON::Syck .PP .SH "AUTHORS" .IX Header "AUTHORS" Audrey Tang .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2005\-2009 by Audrey Tang . .PP This software is released under the \s-1MIT\s0 license cited below. .PP The \fIlibsyck\fR code bundled with this library is released by \&\*(L"why the lucky stiff\*(R", under a BSD-style license. See the \fI\s-1COPYING\s0\fR file for details. .ie n .SS "The ""\s-1MIT""\s0 License" .el .SS "The ``\s-1MIT''\s0 License" .IX Subsection "The MIT License" Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \*(L"Software\*(R"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: .PP The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. .PP \&\s-1THE SOFTWARE IS PROVIDED \*(L"AS IS\*(R", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\s0 PK@O\5ܚ11CPAN::Meta::Requirements.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::Meta::Requirements 3" .TH CPAN::Meta::Requirements 3 "2023-06-19" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::Meta::Requirements \- a set of version requirements for a CPAN dist .SH "VERSION" .IX Header "VERSION" version 2.143 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use CPAN::Meta::Requirements; \& \& my $build_requires = CPAN::Meta::Requirements\->new; \& \& $build_requires\->add_minimum(\*(AqLibrary::Foo\*(Aq => 1.208); \& \& $build_requires\->add_minimum(\*(AqLibrary::Foo\*(Aq => 2.602); \& \& $build_requires\->add_minimum(\*(AqModule::Bar\*(Aq => \*(Aqv1.2.3\*(Aq); \& \& $METAyml\->{build_requires} = $build_requires\->as_string_hash; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" A CPAN::Meta::Requirements object models a set of version constraints like those specified in the \fI\s-1META\s0.yml\fR or \fI\s-1META\s0.json\fR files in \s-1CPAN\s0 distributions, and as defined by CPAN::Meta::Spec. It can be built up by adding more and more constraints, and it will reduce them to the simplest representation. .PP Logically impossible constraints will be identified immediately by thrown exceptions. .SH "METHODS" .IX Header "METHODS" .SS "new" .IX Subsection "new" .Vb 1 \& my $req = CPAN::Meta::Requirements\->new; .Ve .PP This returns a new CPAN::Meta::Requirements object. It takes an optional hash reference argument. Currently, only one key is supported: .IP "\(bu" 4 \&\f(CW\*(C`bad_version_hook\*(C'\fR \*(-- if provided, when a version cannot be parsed into a version object, this code reference will be called with the invalid version string as first argument, and the module name as second argument. It must return a valid version object. .PP All other keys are ignored. .SS "add_minimum" .IX Subsection "add_minimum" .Vb 1 \& $req\->add_minimum( $module => $version ); .Ve .PP This adds a new minimum version requirement. If the new requirement is redundant to the existing specification, this has no effect. .PP Minimum requirements are inclusive. \f(CW$version\fR is required, along with any greater version number. .PP This method returns the requirements object. .SS "add_maximum" .IX Subsection "add_maximum" .Vb 1 \& $req\->add_maximum( $module => $version ); .Ve .PP This adds a new maximum version requirement. If the new requirement is redundant to the existing specification, this has no effect. .PP Maximum requirements are inclusive. No version strictly greater than the given version is allowed. .PP This method returns the requirements object. .SS "add_exclusion" .IX Subsection "add_exclusion" .Vb 1 \& $req\->add_exclusion( $module => $version ); .Ve .PP This adds a new excluded version. For example, you might use these three method calls: .PP .Vb 2 \& $req\->add_minimum( $module => \*(Aq1.00\*(Aq ); \& $req\->add_maximum( $module => \*(Aq1.82\*(Aq ); \& \& $req\->add_exclusion( $module => \*(Aq1.75\*(Aq ); .Ve .PP Any version between 1.00 and 1.82 inclusive would be acceptable, except for 1.75. .PP This method returns the requirements object. .SS "exact_version" .IX Subsection "exact_version" .Vb 1 \& $req\->exact_version( $module => $version ); .Ve .PP This sets the version required for the given module to \fIexactly\fR the given version. No other version would be considered acceptable. .PP This method returns the requirements object. .SS "version_range_for_module" .IX Subsection "version_range_for_module" .Vb 1 \& $req\->version_range_for_module( $another_req_object ); .Ve .SS "add_requirements" .IX Subsection "add_requirements" .Vb 1 \& $req\->add_requirements( $another_req_object ); .Ve .PP This method adds all the requirements in the given CPAN::Meta::Requirements object to the requirements object on which it was called. If there are any conflicts, an exception is thrown. .PP This method returns the requirements object. .SS "accepts_module" .IX Subsection "accepts_module" .Vb 1 \& my $bool = $req\->accepts_module($module => $version); .Ve .PP Given an module and version, this method returns true if the version specification for the module accepts the provided version. In other words, given: .PP .Vb 1 \& Module => \*(Aq>= 1.00, < 2.00\*(Aq .Ve .PP We will accept 1.00 and 1.75 but not 0.50 or 2.00. .PP For modules that do not appear in the requirements, this method will return true. .SS "clear_requirement" .IX Subsection "clear_requirement" .Vb 1 \& $req\->clear_requirement( $module ); .Ve .PP This removes the requirement for a given module from the object. .PP This method returns the requirements object. .SS "requirements_for_module" .IX Subsection "requirements_for_module" .Vb 1 \& $req\->requirements_for_module( $module ); .Ve .PP This returns a string containing the version requirements for a given module in the format described in CPAN::Meta::Spec or undef if the given module has no requirements. This should only be used for informational purposes such as error messages and should not be interpreted or used for comparison (see \&\*(L"accepts_module\*(R" instead). .SS "structured_requirements_for_module" .IX Subsection "structured_requirements_for_module" .Vb 1 \& $req\->structured_requirements_for_module( $module ); .Ve .PP This returns a data structure containing the version requirements for a given module or undef if the given module has no requirements. This should not be used for version checks (see \*(L"accepts_module\*(R" instead). .PP Added in version 2.134. .SS "required_modules" .IX Subsection "required_modules" This method returns a list of all the modules for which requirements have been specified. .SS "clone" .IX Subsection "clone" .Vb 1 \& $req\->clone; .Ve .PP This method returns a clone of the invocant. The clone and the original object can then be changed independent of one another. .SS "is_simple" .IX Subsection "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. .SS "is_finalized" .IX Subsection "is_finalized" This method returns true if the requirements have been finalized by having the \&\f(CW\*(C`finalize\*(C'\fR method called on them. .SS "finalize" .IX Subsection "finalize" This method marks the requirements finalized. Subsequent attempts to change the requirements will be fatal, \fIif\fR they would result in a change. If they would not alter the requirements, they have no effect. .PP If a finalized set of requirements is cloned, the cloned requirements are not also finalized. .SS "as_string_hash" .IX Subsection "as_string_hash" This returns a reference to a hash describing the requirements using the strings in the CPAN::Meta::Spec specification. .PP For example after the following program: .PP .Vb 1 \& my $req = CPAN::Meta::Requirements\->new; \& \& $req\->add_minimum(\*(AqCPAN::Meta::Requirements\*(Aq => 0.102); \& \& $req\->add_minimum(\*(AqLibrary::Foo\*(Aq => 1.208); \& \& $req\->add_maximum(\*(AqLibrary::Foo\*(Aq => 2.602); \& \& $req\->add_minimum(\*(AqModule::Bar\*(Aq => \*(Aqv1.2.3\*(Aq); \& \& $req\->add_exclusion(\*(AqModule::Bar\*(Aq => \*(Aqv1.2.8\*(Aq); \& \& $req\->exact_version(\*(AqXyzzy\*(Aq => \*(Aq6.01\*(Aq); \& \& my $hashref = $req\->as_string_hash; .Ve .PP \&\f(CW$hashref\fR would contain: .PP .Vb 6 \& { \& \*(AqCPAN::Meta::Requirements\*(Aq => \*(Aq0.102\*(Aq, \& \*(AqLibrary::Foo\*(Aq => \*(Aq>= 1.208, <= 2.206\*(Aq, \& \*(AqModule::Bar\*(Aq => \*(Aq>= v1.2.3, != v1.2.8\*(Aq, \& \*(AqXyzzy\*(Aq => \*(Aq== 6.01\*(Aq, \& } .Ve .SS "add_string_requirement" .IX Subsection "add_string_requirement" .Vb 2 \& $req\->add_string_requirement(\*(AqLibrary::Foo\*(Aq => \*(Aq>= 1.208, <= 2.206\*(Aq); \& $req\->add_string_requirement(\*(AqLibrary::Foo\*(Aq => v1.208); .Ve .PP This method parses the passed in string and adds the appropriate requirement for the given module. A version can be a Perl \*(L"v\-string\*(R". It understands version ranges as described in the \*(L"Version Ranges\*(R" in CPAN::Meta::Spec. For example: .IP "1.3" 4 .IX Item "1.3" .PD 0 .IP ">= 1.3" 4 .IX Item ">= 1.3" .IP "<= 1.3" 4 .IX Item "<= 1.3" .IP "== 1.3" 4 .IX Item "== 1.3" .IP "!= 1.3" 4 .IX Item "!= 1.3" .IP "> 1.3" 4 .IX Item "> 1.3" .IP "< 1.3" 4 .IX Item "< 1.3" .IP ">= 1.3, != 1.5, <= 2.0" 4 .IX Item ">= 1.3, != 1.5, <= 2.0" .PD A version number without an operator is equivalent to specifying a minimum (\f(CW\*(C`>=\*(C'\fR). Extra whitespace is allowed. .SS "from_string_hash" .IX Subsection "from_string_hash" .Vb 2 \& my $req = CPAN::Meta::Requirements\->from_string_hash( \e%hash ); \& my $req = CPAN::Meta::Requirements\->from_string_hash( \e%hash, \e%opts ); .Ve .PP This is an alternate constructor for a CPAN::Meta::Requirements object. It takes a hash of module names and version requirement strings and returns a new CPAN::Meta::Requirements object. As with add_string_requirement, a version can be a Perl \*(L"v\-string\*(R". Optionally, you can supply a hash-reference of options, exactly as with the \*(L"new\*(R" method. .SH "SUPPORT" .IX Header "SUPPORT" .SS "Bugs / Feature Requests" .IX Subsection "Bugs / Feature Requests" Please report any bugs or feature requests through the issue tracker at . You will be notified automatically of any progress on your issue. .SS "Source Code" .IX Subsection "Source Code" This is open source software. The code repository is available for public review and contribution under the terms of the license. .PP .PP .Vb 1 \& git clone https://github.com/Perl\-Toolchain\-Gang/CPAN\-Meta\-Requirements.git .Ve .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 David Golden .IP "\(bu" 4 Ricardo Signes .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Ed J .IP "\(bu" 4 Graham Knop .IP "\(bu" 4 Karen Etheridge .IP "\(bu" 4 Leon Timmermans .IP "\(bu" 4 Paul Howarth .IP "\(bu" 4 Ricardo Signes .IP "\(bu" 4 robario .IP "\(bu" 4 Tatsuhiko Miyagawa .IP "\(bu" 4 Tatsuhiko Miyagawa .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2010 by David Golden and Ricardo Signes. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK@O\ Y YPOD2::DE::local::lib.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "POD2::DE::local::lib 3" .TH POD2::DE::local::lib 3 "2019-11-14" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" local::lib~[de] \- Erschaffen und benutzen von Perl Modulen in einem lokalen lib/ Verzeichnis mit PERL5LIB .SH "SYNOPSIS" .IX Header "SYNOPSIS" Im Code \- .PP .Vb 1 \& use local::lib; # Benutzt das Verzeichnis ~/perl5 zum anlegen des lokalen lib/ Verzeichnisses \& \& use local::lib \*(Aq~/foo\*(Aq; # das selbe, aber mit ~/foo \& \& # Oder... \& use FindBin; \& use local::lib "$FindBin::Bin/../support"; # Applikationsspezifische Sammlung von Modulen .Ve .PP Von der Shell \- .PP .Vb 2 \& # Installiert LWP und alle notwendigen Abhängigkeiten in das \*(Aq~/perl5\*(Aq Verzeichnis \& perl \-MCPAN \-Mlocal::lib \-e \*(AqCPAN::install(LWP)\*(Aq \& \& # Gibt die Shell Kommandos aus um die Umgebung vorzubereiten \& $ perl \-Mlocal::lib \& export PERL_MB_OPT=\*(Aq\-\-install_base /home/username/perl5\*(Aq \& export PERL_MM_OPT=\*(AqINSTALL_BASE=/home/username/perl5\*(Aq \& export PERL5LIB=\*(Aq/home/username/perl5/lib/perl5/i386\-linux:/home/username/perl5/lib/perl5\*(Aq \& export PATH="/home/username/perl5/bin:$PATH" .Ve .SS "Die Bootstrapping Methode" .IX Subsection "Die Bootstrapping Methode" Ein typischer Weg um local::lib zu benutzen ist die sogenannte \*(L"Bootstrapping\*(R" Methode. Diese Methode wird benutzt wenn noch kein local::lib auf dem System installiert ist. In diesem Fall kannst du einfach local::lib direkt in deinem Home-Verzeichnis installieren. .PP Selbst wenn du administrative Rechte hast, ist es wichtig das die Umgebungsvariablen von Schritt 4 in deinem Shell Startup Skript gesetzt werden. Ohne diesen Schritt werden die Module von \s-1CPAN\s0 weiterhin im System installiert und auch Perl Skripte die du startest würden das von local::lib erstellte lib/ Verzeichnis nicht nutzen. .PP Standardmäßig installiert sich local::lib in ~/perl5. .PP Windows Benutzern müssen ausserdem dies hier lesen: \&\*(L"Unterschiede bei Benutzung dieses Module mit Win32\*(R". .PP 1. Lade das Tar-Archiv von \s-1CPAN\s0 runter (Suche nach \*(L"Download\*(R" auf der \s-1CPAN\s0 Seite von local::lib) und entpacke es in einem beliebigem Verzeichnis. Um das obige Problem zu vermeiden, sollte man dies als normaler User tun und nicht als root oder Administrator. .PP 2. Starte in dem entstandenen Verzeichnis folgenden Befehl: .PP .Vb 1 \& perl Makefile.PL \-\-bootstrap .Ve .PP Wenn das System dir vorschlägt gewisse Dinge eigenständig zu konfigurieren ist es in fast allen Fällen vollkommen in Ordnung einfach \*(L"yes\*(R" zu antworten. .PP Falls du local::lib nicht in das Standard Verzeichnis installieren willst, musst du dieses Verzeichnis als Parameter angeben: .PP .Vb 1 \& perl Makefile.PL \-\-bootstrap=~/foo .Ve .PP 3. Danach folgenden Befehl starten: (local::lib erwartet make auf dem System) .PP .Vb 1 \& make test && make install .Ve .PP 4. Nun müssen wir die benötigten Umgebungsvariablen, damit Perl unser neu generiertes lib/ Verzeichnis benutzt. Wenn du bash oder eine andere Bourne Shell benutzt, kannst du es über diesen Weg zu deinem Shell Startup Skript hinzufügen: .PP .Vb 1 \& echo \*(Aqeval $(perl \-I$HOME/perl5/lib/perl5 \-Mlocal::lib)\*(Aq >>~/.bashrc .Ve .PP Wenn du C Shell benutzt, du kannst das gleiche hiermit erreichen: .PP .Vb 4 \& /bin/csh \& echo $SHELL \& /bin/csh \& perl \-I$HOME/perl5/lib/perl5 \-Mlocal::lib >> ~/.cshrc .Ve .PP Wenn du beim bootstrappen ein anderes Verzeichnis benutzt als das Standardverzeichnis, dann musst du dieses Verzeichnis als Parameter beim Laden des Modules local::lib angeben: .PP .Vb 1 \& echo \*(Aqeval $(perl \-I$HOME/foo/lib/perl5 \-Mlocal::lib=$HOME/foo)\*(Aq >>~/.bashrc .Ve .PP Nachdem diese Änderungen in deinem Shell Startup Skript gemacht wurden, ist es nun wichtig das diese Umgebungsvariablen auch gesetzt sind in deiner aktuellen Umgebung. In Bourne Shells macht man dies z.B. mit \f(CW\*(C`. ~/.bashrc\*(C'\fR, und in C Shell würde man es mit: \&\f(CW\*(C`source ~/.cshrc\*(C'\fR mit. .PP Wenn du eine sehr langsames System hast, oder du unter drakonischen Regulierungen des Plattenplatz leben musst, kann man die automatische Generierung der manpages vom \s-1POD\s0 bei der Installation des Moduls deaktivieren beim bootstrapping mit dem \f(CW\*(C`\-\-no\-manpages\*(C'\fR Parameter: .PP .Vb 1 \& perl Makefile.PL \-\-bootstrap \-\-no\-manpages .Ve .PP Um zu vermeiden das man mehrere bootstraps macht um z.B. für verschiedene Applikationen eigene local::lib Installationen zu nutzen, kann man eine dieser Umgebungen benutzen um einfach in beliebigen anderen Verzeichnis Module zu installieren und somit weitere eigenständige lib/ Umgebungen zu bekommen: .PP .Vb 4 \& cd ~/mydir1 \& perl \-Mlocal::lib=./ \& eval $(perl \-Mlocal::lib=./) ### Um die Umgebungsvariablen für die \& ### aktuelle Shell zusetzen \& \& printenv ### Hier kannst du sehen das ~/mydir1 \& ### in der PERL5LIB Umgebungsvariable \& ### steht \& \& perl \-MCPAN \-e install ... ### welche Module auch immer ... \& cd ../mydir2 \& \& ... WIEDERHOLEN ... .Ve .PP Für mehrere Umgebungen in dieser Form brauch man eine Modifikation in der Benutzung von \f(CW\*(C`use FindBin\*(C'\fR in dem \*(L"Im Code\*(R" Beispiel oben. Wenn du sowas machst, und du hast damit z.B. Perl Module nach \f(CW\*(C`~/mydir1/lib\*(C'\fR installiert und du hast ein Script in \f(CW\*(C`~/mydir1/scripts/myscript.pl\*(C'\fR, du musst dort angeben das die Module die es braucht im Verzeichnis \f(CW\*(C`~/mydir1/lib\*(C'\fR liegen. .PP In \f(CW\*(C`~/mydir1/scripts/myscript.pl\*(C'\fR steht dann: .PP .Vb 5 \& use strict; \& use warnings; \& use local::lib "$FindBin::Bin/.."; ### zeigt auf ~/mydir1 und local::lib \& ### findet dort lib \& use lib "$FindBin::Bin/../lib"; ### zeigt auf ~/mydir1/lib .Ve .PP Setze das vor jeden \s-1BEGIN\s0 { ... } Block der die Module braucht die du installiert hast. .SS "Unterschiede bei Benutzung dieses Module mit Win32" .IX Subsection "Unterschiede bei Benutzung dieses Module mit Win32" Um die nötigen Umgebungsvariablen für diese Variablen in der derzeitigen Sitzung mit \f(CW\*(C`CMD.EXE\*(C'\fR zu setzen, kann man folgendes kommando nutzen: .PP .Vb 5 \& C:\e>perl \-Mlocal::lib \& set PERL_MB_OPT=\-\-install_base C:\eDOCUME~1\eADMINI~1\eperl5 \& set PERL_MM_OPT=INSTALL_BASE=C:\eDOCUME~1\eADMINI~1\eperl5 \& set PERL5LIB=C:\eDOCUME~1\eADMINI~1\eperl5\elib\eperl5;C:\eDOCUME~1\eADMINI~1\eperl5\elib\eperl5\eMSWin32\-x86\-multi\-thread \& set PATH=C:\eDOCUME~1\eADMINI~1\eperl5\ebin;%PATH% \& \& ### Um die Umgebungsvariablen für diese Shell alleine zu setzen \& C:\e>perl \-Mlocal::lib > %TEMP%\etmp.bat && %TEMP%\etmp.bat && del %TEMP%\etemp.bat \& ### anstelle von $(perl \-Mlocal::lib=./) in bash. .Ve .PP Wenn du willst das die Umgebungsvariablen dauerhaft gesetzt sind, musst du diese in Systemsteuerung / System dauerhaft selber eintragen oder App::local::lib::Win32Helper benutzen. .PP Die \*(L"~\*(R" wird übersetzt zu dem Benutzer Profil Verzeichnis (das Verzeichnis was beim User als \*(L"Dokumente und Einstellungen\*(R" bekannt ist unter Windows \s-1XP\s0 und vorher oder das \*(L"Benutzer\*(R" Verzeichnis bei Windows Vista und später), solange \&\f(CW$ENV\fR{\s-1HOME\s0} nicht gesetzt ist. Das Verzeichnis wird hierbei zu dem korrekten Kurznamen umgewandelt, und muss daher definitiv existieren, und wird um die nötigen Unterverzeichnise erweitert. .SH "GRUNDPRINZIP" .IX Header "GRUNDPRINZIP" Die Version von den Perl Paketen die man benötigt für spezifische Aufgaben sind sehr häufig nicht die richtigen oder korrekten Versionen auf dem System vorinstalliert. Ein Updaten von diesen Modulen ist in vielen Fällen einfach nicht möglich weil die nötigen Rechte fehlen. Ausserdem ist es generell nicht gut eigenständig die Versionen der Module auf dem System auszutauschen, weil natürlich der Rest des Systems genau die Version erwartet die von der Systemverwaltung auch installiert wurde. .PP local::lib löst dieses Problem, es erlaubt dir dein komplett eigenes Verzeichnis für deine \s-1CPAN\s0 Module zu haben und bist so nicht genötigt die Module vom System zu nutzen oder andersrum andere User nicht mit individuellen Modulwünschen zu Überarbeitung ihres Codes zu zwingen, weil bestimmte Module zentral für alle auf neuere Version upgedatet werden. Die Installation findet hierbei dann z.B. im Home Verzeichnis statt. Es werden nur Umgebungsvariablen gesetzt die das installierte Perl dazu bewegen die im Homeverzeichnis installierten Module zu benutzen, zusätzlich und vorgezogen zu denen auf dem System. .PP Daher muss man sich wenn man ein Paket System benutzt, wie z.b. Debian, garnicht mehr Sorgen machen, irgendwas auf dem System zu verletzten nur durch die Installation von Perl Modulen. .SH "BESCHREIBUNG" .IX Header "BESCHREIBUNG" Dieses Modul bietet eine schnelle und legitime Art und Weise ein sogenanntes bootstrapping zu machen um in einem User Homeverzeichnis eine Sammlung von Modulen zu installieren. Es erstellt auch die nötigen Umgebungsvariablen die benötigt werden um diese Module zu nutzen, passend zu der Shell die der User in der Umgebungsvariable \f(CW\*(C`SHELL\*(C'\fR angegeben hat, um dann direkt passend in die entsprechenden Konfigurationsdateien der Shell einfügt zu werden. .PP Weitergehend ist local::lib in der Lage Module zu nutzen die nicht im standardmäßigen \f(CW@INC\fR Pfad von Perl enthalten sind. Das macht es einfacher für bestimmte Applikationen ein bestimmtes Set von Modulen zu installieren ohne die anderen Module auf dem System in irgendeiner Art anzufassen. Damit es z.B. auch sicherer Module zu installieren die vom Maintainer noch nicht als Release verfügbar sind. .PP Beim Import setzt local::lib die folgenden Umgebungsvariablen zu den nötigen Werten: .IP "\s-1PERL_MB_OPT\s0" 4 .IX Item "PERL_MB_OPT" .PD 0 .IP "\s-1PERL_MM_OPT\s0" 4 .IX Item "PERL_MM_OPT" .IP "\s-1PERL5LIB\s0" 4 .IX Item "PERL5LIB" .IP "\s-1PATH\s0" 4 .IX Item "PATH" .PD Am \s-1PATH\s0 wird natürlich angehangen, und nicht ersetzt. .PP Diese Werte sind dann verfügbar für jeden Code der danach importiert wurde. .SH "ERSTELLEN EINES EIGENSTÄNDIGE SAMMLUNG VON MODULEN" .IX Header "ERSTELLEN EINES EIGENSTÄNDIGE SAMMLUNG VON MODULEN" Mit lib::core::only besteht eine Möglichkeit dieses zutun, aber beachte das hier eine Menge von Fallstricken und Problemen existieren, und man sollte immer darauf achten das man auf einem Perl aufbaut was sowenig wie möglich verändert wurde (d.h. site und vendor Verzeichnis so leer wie möglich). .SH "METHODEN" .IX Header "METHODEN" .SS "ensure_dir_structure_for" .IX Subsection "ensure_dir_structure_for" .ie n .IP "Parameter: $path" 4 .el .IP "Parameter: \f(CW$path\fR" 4 .IX Item "Parameter: $path" .PD 0 .IP "Rückgabewert: Keiner" 4 .IX Item "Rückgabewert: Keiner" .PD .PP Versucht den angegebenen Pfad anzulegen, mit allen nötigen drüberliegenden Verzeichnissen. Im Fehlerfall wird eine Exception geworfen. .SS "print_environment_vars_for" .IX Subsection "print_environment_vars_for" .ie n .IP "Parameter: $pfad" 4 .el .IP "Parameter: \f(CW$pfad\fR" 4 .IX Item "Parameter: $pfad" .PD 0 .IP "Rückgabewert: Keiner" 4 .IX Item "Rückgabewert: Keiner" .PD .PP Gibt die Umgebungsvariablen aus, die benötigt werden um den angegebenen Pfad als Basis Verzeichnis zu nutzen. .SS "build_environment_vars_for" .IX Subsection "build_environment_vars_for" .ie n .IP "Parameter: $pfad, $interpolate" 4 .el .IP "Parameter: \f(CW$pfad\fR, \f(CW$interpolate\fR" 4 .IX Item "Parameter: $pfad, $interpolate" .PD 0 .IP "Rückgabewert: \e%umgebungs_variablen" 4 .IX Item "Rückgabewert: %umgebungs_variablen" .PD .PP Gibt ein Hash zurück mit den Variablen die nötig sind in den Umgebungsvariablen um eine Installation in dem gegebenen Pfad zu benutzen. .SS "setup_env_hash_for" .IX Subsection "setup_env_hash_for" .ie n .IP "Parameter: $pfad" 4 .el .IP "Parameter: \f(CW$pfad\fR" 4 .IX Item "Parameter: $pfad" .PD 0 .IP "Rückgabewert: Keiner" 4 .IX Item "Rückgabewert: Keiner" .PD .PP Setzt die \f(CW%ENV\fR Einträge basierend auf dem Aufruf von \&\*(L"build_environment_vars_for\*(R". .SS "install_base_perl_path" .IX Subsection "install_base_perl_path" .ie n .IP "Parameter: $pfad" 4 .el .IP "Parameter: \f(CW$pfad\fR" 4 .IX Item "Parameter: $pfad" .PD 0 .ie n .IP "Rückgabewert: $module_installations_pfad" 4 .el .IP "Rückgabewert: \f(CW$module_installations_pfad\fR" 4 .IX Item "Rückgabewert: $module_installations_pfad" .PD .PP Gibt den Pfad zurück der benutzt wird um Perl Module zu installieren bei dem gegebenen Pfad als Basis. Prinzipiell wird nur \f(CW\*(C`lib\*(C'\fR und \f(CW\*(C`perl5\*(C'\fR als Pfadelemente angehangen. .SS "install_base_arch_path" .IX Subsection "install_base_arch_path" .ie n .IP "Parameter: $pfad" 4 .el .IP "Parameter: \f(CW$pfad\fR" 4 .IX Item "Parameter: $pfad" .PD 0 .ie n .IP "Rückgabewert: $architektur_module_installations_pfad" 4 .el .IP "Rückgabewert: \f(CW$architektur_module_installations_pfad\fR" 4 .IX Item "Rückgabewert: $architektur_module_installations_pfad" .PD .PP Gibt den Pfad zurück der benutzt wird um die Architektur\-abhängigen Perl Module zu installieren basirend auf dem angegebenen Pfad als Basis. Basierend auf dem was \*(L"install_base_perl_path\*(R" zurückgibt, and appends the value of \&\f(CW$Config{archname}\fR.asis. .SS "install_base_bin_path" .IX Subsection "install_base_bin_path" .ie n .IP "Parameter: $pfad" 4 .el .IP "Parameter: \f(CW$pfad\fR" 4 .IX Item "Parameter: $pfad" .PD 0 .ie n .IP "Rückgabewert: $ausfuehrbare_programme_installations_pfad" 4 .el .IP "Rückgabewert: \f(CW$ausfuehrbare_programme_installations_pfad\fR" 4 .IX Item "Rückgabewert: $ausfuehrbare_programme_installations_pfad" .PD .PP Gibt den Pfad zurück, wo ausführbare Programme installiert werden, basierend auf der Basis des angegebenen Pfad. Basierend auf \*(L"install_base_perl_path\*(R" Rückgabewert, hängt diese Methode noch \f(CW\*(C`bin\*(C'\fR an. .SS "resolve_empty_path" .IX Subsection "resolve_empty_path" .ie n .IP "Parameter: $pfad" 4 .el .IP "Parameter: \f(CW$pfad\fR" 4 .IX Item "Parameter: $pfad" .PD 0 .ie n .IP "Rückgabewert: $basis_pfad" 4 .el .IP "Rückgabewert: \f(CW$basis_pfad\fR" 4 .IX Item "Rückgabewert: $basis_pfad" .PD .PP Erstellt und gibt zurück den Pfad der benutzt wird als Basis zur Installation der Module. Standardmäßig dies ist \f(CW\*(C`~/perl5\*(C'\fR. .ie n .SS "resolve_home_path( $path )" .el .SS "resolve_home_path( \f(CW$path\fP )" .IX Subsection "resolve_home_path( $path )" .ie n .IP "Parameter: $pfad" 4 .el .IP "Parameter: \f(CW$pfad\fR" 4 .IX Item "Parameter: $pfad" .PD 0 .ie n .IP "Rückgabewert: $home" 4 .el .IP "Rückgabewert: \f(CW$home\fR" 4 .IX Item "Rückgabewert: $home" .PD .PP Versucht das Home Verzeichnis vom aktullen User zu finden. Es wird eine Exception geworfen, wenn kein Home Verzeichnis ermittelt werden konnte. .SS "resolve_relative_path" .IX Subsection "resolve_relative_path" .ie n .IP "Parameter: $pfad" 4 .el .IP "Parameter: \f(CW$pfad\fR" 4 .IX Item "Parameter: $pfad" .PD 0 .ie n .IP "Rückgabewert: $absoluter_pfad" 4 .el .IP "Rückgabewert: \f(CW$absoluter_pfad\fR" 4 .IX Item "Rückgabewert: $absoluter_pfad" .PD .PP Macht aus dem angegebenen Pfad einen absoluten Pfad. .SS "resolve_path" .IX Subsection "resolve_path" .ie n .IP "Parameter: $pfad" 4 .el .IP "Parameter: \f(CW$pfad\fR" 4 .IX Item "Parameter: $pfad" .PD 0 .ie n .IP "Rückgabewert: $absoluter_pfad" 4 .el .IP "Rückgabewert: \f(CW$absoluter_pfad\fR" 4 .IX Item "Rückgabewert: $absoluter_pfad" .PD .PP Hierbei wird der Pfad durch die folgende Methoden gegeben, wobei der Rückgabewert der ersten an die nächste weitergeben wird, um die Umgebung zu konfigurieren für die lokale Bibliotheks Installation: \*(L"resolve_empty_path\*(R", \&\*(L"resolve_home_path\*(R", \*(L"resolve_relative_path\*(R". Der daraus resultierende Pfad wird zu \*(L"resolve_empty_path\*(R" übergeben, dessen Resultat dann weitergegeben wird an \*(L"resolve_home_path\*(R", wessen Resultat dann weitergegeben wird an \*(L"resolve_relative_path\*(R". Dieses Resultat wird dann final an \*(L"resolve_path\*(R" übergeben, welches dann den Rückgabewert stellt. .SH "EINE WARNUNG VOR UNINST=1" .IX Header "EINE WARNUNG VOR UNINST=1" Wenn man local::lib in Kombination mit \*(L"make install UNINST=1\*(R" benutzt, muss man vorsichtig sein über die Tatsache das der Prozess über die Neuinstallation eine nicht ausreichende Sicherheit hat bezüglich wo er nun installieren muss. Hierdurch mann es passieren das beim deinstallieren eines Modul u.U. das globale Modul deinstalliert wird (wenn die Rechte vorhanden sind) aber die neue Version nur in der lokalen Version installiert ist. Es ist hier also sehr wichtig das man \*(L"make install UNINST=1\*(R" und local::lib nur gleichzeitig benutzt wenn man sehr sicher darüber ist welche Konsequenzen einem entgegenkommen. .SH "EINSCHRÄNKUNGEN" .IX Header "EINSCHRÄNKUNGEN" Die Werkzeuge von perl, die benutzt werden um die Pakete zu installieren (die sogenannte toolchain), sind leider nicht in der Lage sauber mit Verzeichnissen umzugehen die Leerzeichen enthalten und können daher local::lib nicht direkt in ein solches Verzeichnis installieren. Was du machen kannst ist \fBnach\fR der Installation von local::lib und der Module die du in deiner local::lib haben willst, das gesamte Verzeichnis dahin zu bewegen. local::lib kann mit dem Verzeichnis mit Leerzeichen umgehen. Bitte aufpassen das natürlich eine weitere Installation oder ein Erneuern von Paketen mit dem \s-1CPAN\s0 Programm nicht mehr möglich ist. .PP Die Shell Erkennung ist sehr primitiv. Derzeit ist es so das alles was \*(L"csh\*(R" im Namen hat auch als C Shell eingeordnet wird, und alles andere wird als Bourne Shell betrachet, ausser auf Win32 Systemen. Wenn die \f(CW\*(C`SHELL\*(C'\fR Variable nicht gesetzt ist, eine Bourne Shell wird angenommen. .PP Bootstrap ist leider ein Hack, und wird auf jedenfall \s-1CPAN\s0.pm benutzen für ExtUtils::MakeMaker, auch wenn \s-1CPANPLUS\s0 installiert ist. .PP Es setzt definitiv \s-1PERL5LIB, PERL_MM_OPT\s0 und \s-1PERL_MB_OPT\s0 neu und vernichtet jeden Wert der vorher gesetzt war. .PP Es sollte vielleicht eine automatische Korrektur der \s-1CPAN\s0 Config machen, wenn das nicht schon gemacht wurde. .PP \&\*(L"Patches Welcome\*(R" \- Patches sind immer willkommen beim Autor oder den anderen Mitwirkenden. .PP Auf Win32 Systemen werden die Umgebungsvariablen nicht direkt in die Registrierung geschrieben damit sie auch nach dem Neustarten erhalten bleiben. .SH "FEHLERANALYSE" .IX Header "FEHLERANALYSE" Wenn du local::lib konfiguriert hast \s-1CPAN\s0 Module in deinem Home Verzeichnis zu installieren, und du danach versuchst mit \f(CW\*(C`cpan \-i Foo::Bar\*(C'\fR ein Modul zu installieren, und dabei einen Fehler bekommst, wie: \f(CW\*(C`Warning: You do not have permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64\-linux at /usr/lib64/perl5/5.8.8/Foo/Bar.pm\*(C'\fR und in der installationsausgabe steht irgendwo ein Fehler der sagt \f(CW\*(C`\*(AqINSTALL_BASE\*(Aq is not a known MakeMaker parameter name\*(C'\fR, dann hast du aus irgendeinem Grund dein neue Version von ExtUtils::MakeMaker verloren. .PP Um dies zu korrigieren, einfach nochmal die bootstrapping Methode laufen lassen, wie oben beschrieben. .PP Dann starte \f(CW\*(C`rm \-r ~/.cpan/build/Foo\-Bar*\*(C'\fR .PP Abschliessend dann nochmal mit \f(CW\*(C`cpan \-i Foo::Bar\*(C'\fR installieren und die Probleme sollten verschwunden sein. .SH "UMGEBUNGSVARIABLEN" .IX Header "UMGEBUNGSVARIABLEN" .IP "\s-1SHELL\s0" 4 .IX Item "SHELL" .PD 0 .IP "\s-1COMSPEC\s0" 4 .IX Item "COMSPEC" .PD local::lib schaut in die \f(CW\*(C`SHELL\*(C'\fR Umgebungsvariable um die korrekten Kommandos zu der Shell Konfiguration hinzuzufügen. .Sp Auf Win32 Systemen, \f(CW\*(C`COMSPEC\*(C'\fR wird auch analysiert. .SH "SUPPORT" .IX Header "SUPPORT" \&\s-1IRC:\s0 .PP .Vb 1 \& Wir sind im Channel #local\-lib auf dem Server irc.perl.org. .Ve .SH "AUTOR DER ÜBERSETZUNG" .IX Header "AUTOR DER ÜBERSETZUNG" Torsten Raudssus http://www.raudssus.de/ .SH "URHEBERRECHT" .IX Header "URHEBERRECHT" Copyright (c) 2007 \- 2010 von den local::lib \*(L"\s-1AUTHOR\*(R"\s0 in local::lib und \*(L"\s-1CONTRIBUTORS\*(R"\s0 in local::lib aufgelistet in local::lib. .SH "LIZENZ" .IX Header "LIZENZ" Diese Sammlung ist freie Software und kann unter der selben Lizenz verbreitet werden wie Perl selber. PK@O\Hy CPAN::Version.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::Version 3" .TH CPAN::Version 3 "2018-09-22" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::Version \- utility functions to compare CPAN versions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use CPAN::Version; \& \& CPAN::Version\->vgt("1.1","1.1.1"); # 1 bc. 1.1 > 1.001001 \& \& CPAN::Version\->vlt("1.1","1.1"); # 0 bc. 1.1 not < 1.1 \& \& CPAN::Version\->vcmp("1.1","1.1.1"); # 1 bc. first is larger \& \& CPAN::Version\->vcmp("1.1.1","1.1"); # \-1 bc. first is smaller \& \& CPAN::Version\->readable(v1.2.3); # "v1.2.3" \& \& CPAN::Version\->vstring("v1.2.3"); # v1.2.3 \& \& CPAN::Version\->float2vv(1.002003); # "v1.2.3" .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module mediates between some version that perl sees in a package and the version that is published by the \s-1CPAN\s0 indexer. .PP It's only written as a helper module for both \s-1CPAN\s0.pm and \s-1CPANPLUS\s0.pm. .PP As it stands it predates version.pm but has the same goal: make version strings visible and comparable. .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK@O\/LLCanary::Stability.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Stability 3" .TH Stability 3 "2019-04-22" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Canary::Stability \- canary to check perl compatibility for schmorp's modules .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # in Makefile.PL \& use Canary::Stability DISTNAME => 2001, MINIMUM_PERL_VERSION; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module is used by Schmorp's modules during configuration stage to test the installed perl for compatibility with his modules. .PP It's not, at this stage, meant as a tool for other module authors, although in principle nothing prevents them from subscribing to the same ideas. .PP See the \fIMakefile.PL\fR in Coro or AnyEvent for usage examples. .SH "ENVIRONMENT VARIABLES" .IX Header "ENVIRONMENT VARIABLES" .ie n .IP """PERL_CANARY_STABILITY_NOPROMPT=1""" 4 .el .IP "\f(CWPERL_CANARY_STABILITY_NOPROMPT=1\fR" 4 .IX Item "PERL_CANARY_STABILITY_NOPROMPT=1" Do not prompt the user on alert messages. .ie n .IP """PERL_CANARY_STABILITY_COLOUR=0""" 4 .el .IP "\f(CWPERL_CANARY_STABILITY_COLOUR=0\fR" 4 .IX Item "PERL_CANARY_STABILITY_COLOUR=0" Disable use of colour. .ie n .IP """PERL_CANARY_STABILITY_COLOUR=1""" 4 .el .IP "\f(CWPERL_CANARY_STABILITY_COLOUR=1\fR" 4 .IX Item "PERL_CANARY_STABILITY_COLOUR=1" Force use of colour. .ie n .IP """PERL_CANARY_STABILITY_DISABLE=1""" 4 .el .IP "\f(CWPERL_CANARY_STABILITY_DISABLE=1\fR" 4 .IX Item "PERL_CANARY_STABILITY_DISABLE=1" Disable this modules functionality completely. .ie n .IP """AUTOMATED_TESTING=1""" 4 .el .IP "\f(CWAUTOMATED_TESTING=1\fR" 4 .IX Item "AUTOMATED_TESTING=1" When this variable is set to a true value and the perl minimum version requirement is not met, the module will exit, which should skip testing under automated testing environments. .Sp This is done to avoid false failure or success reports when the chances of success are already quite low and the failures are not supported by the author. .SH "AUTHOR" .IX Header "AUTHOR" .Vb 2 \& Marc Lehmann \& http://software.schmorp.de/pkg/Canary\-Stability.html .Ve PK@O\W]# %%#CPAN::Meta::Requirements::Range.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::Meta::Requirements::Range 3" .TH CPAN::Meta::Requirements::Range 3 "2023-06-19" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::Meta::Requirements::Range \- a set of version requirements for a CPAN dist .SH "VERSION" .IX Header "VERSION" version 2.143 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use CPAN::Meta::Requirements::Range; \& \& my $range = CPAN::Meta::Requirements::Range\->with_minimum(1); \& \& $range = $range\->with_maximum(\*(Aqv2.2\*(Aq); \& \& my $stringified = $range\->as_string; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" A CPAN::Meta::Requirements::Range object models a set of version constraints like those specified in the \fI\s-1META\s0.yml\fR or \fI\s-1META\s0.json\fR files in \s-1CPAN\s0 distributions, and as defined by CPAN::Meta::Spec; It can be built up by adding more and more constraints, and it will reduce them to the simplest representation. .PP Logically impossible constraints will be identified immediately by thrown exceptions. .SH "METHODS" .IX Header "METHODS" .SS "with_string_requirement" .IX Subsection "with_string_requirement" .Vb 2 \& $req\->with_string_requirement(\*(Aq>= 1.208, <= 2.206\*(Aq); \& $req\->with_string_requirement(v1.208); .Ve .PP This method parses the passed in string and adds the appropriate requirement. A version can be a Perl \*(L"v\-string\*(R". It understands version ranges as described in the \*(L"Version Ranges\*(R" in CPAN::Meta::Spec. For example: .IP "1.3" 4 .IX Item "1.3" .PD 0 .IP ">= 1.3" 4 .IX Item ">= 1.3" .IP "<= 1.3" 4 .IX Item "<= 1.3" .IP "== 1.3" 4 .IX Item "== 1.3" .IP "!= 1.3" 4 .IX Item "!= 1.3" .IP "> 1.3" 4 .IX Item "> 1.3" .IP "< 1.3" 4 .IX Item "< 1.3" .IP ">= 1.3, != 1.5, <= 2.0" 4 .IX Item ">= 1.3, != 1.5, <= 2.0" .PD A version number without an operator is equivalent to specifying a minimum (\f(CW\*(C`>=\*(C'\fR). Extra whitespace is allowed. .SS "with_range" .IX Subsection "with_range" .Vb 1 \& $range\->with_range($other_range) .Ve .PP This creates a new range object that is a merge two others. .SS "with_exact_version" .IX Subsection "with_exact_version" .Vb 1 \& $range\->with_exact_version( $version ); .Ve .PP This sets the version required to \fIexactly\fR the given version. No other version would be considered acceptable. .PP This method returns the version range object. .SS "with_minimum" .IX Subsection "with_minimum" .Vb 1 \& $range\->with_minimum( $version ); .Ve .PP This adds a new minimum version requirement. If the new requirement is redundant to the existing specification, this has no effect. .PP Minimum requirements are inclusive. \f(CW$version\fR is required, along with any greater version number. .PP This method returns the version range object. .SS "with_maximum" .IX Subsection "with_maximum" .Vb 1 \& $range\->with_maximum( $version ); .Ve .PP This adds a new maximum version requirement. If the new requirement is redundant to the existing specification, this has no effect. .PP Maximum requirements are inclusive. No version strictly greater than the given version is allowed. .PP This method returns the version range object. .SS "with_exclusion" .IX Subsection "with_exclusion" .Vb 1 \& $range\->with_exclusion( $version ); .Ve .PP This adds a new excluded version. For example, you might use these three method calls: .PP .Vb 2 \& $range\->with_minimum( \*(Aq1.00\*(Aq ); \& $range\->with_maximum( \*(Aq1.82\*(Aq ); \& \& $range\->with_exclusion( \*(Aq1.75\*(Aq ); .Ve .PP Any version between 1.00 and 1.82 inclusive would be acceptable, except for 1.75. .PP This method returns the requirements object. .SS "as_struct" .IX Subsection "as_struct" .Vb 1 \& $range\->as_struct( $module ); .Ve .PP This returns a data structure containing the version requirements. This should not be used for version checks (see \*(L"accepts_module\*(R" instead). .SS "as_string" .IX Subsection "as_string" .Vb 1 \& $range\->as_string; .Ve .PP This returns a string containing the version requirements in the format described in CPAN::Meta::Spec. This should only be used for informational purposes such as error messages and should not be interpreted or used for comparison (see \*(L"accepts\*(R" instead). .SS "accepts" .IX Subsection "accepts" .Vb 1 \& my $bool = $range\->accepts($version); .Ve .PP Given a version, this method returns true if the version specification accepts the provided version. In other words, given: .PP .Vb 1 \& \*(Aq>= 1.00, < 2.00\*(Aq .Ve .PP We will accept 1.00 and 1.75 but not 0.50 or 2.00. .SS "is_simple" .IX Subsection "is_simple" This method returns true if and only if the range is an inclusive minimum \&\*(-- that is, if their string expression is just the version number. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 David Golden .IP "\(bu" 4 Ricardo Signes .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2010 by David Golden and Ricardo Signes. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK@O\stb b CPAN::Debug.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::Debug 3" .TH CPAN::Debug 3 "2016-08-17" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::Debug \- internal debugging for CPAN.pm .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK@O\r4J||local::lib.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "local::lib 3" .TH local::lib 3 "2022-04-20" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" local::lib \- create and use a local lib/ for perl modules with PERL5LIB .SH "SYNOPSIS" .IX Header "SYNOPSIS" In code \- .PP .Vb 1 \& use local::lib; # sets up a local lib at ~/perl5 \& \& use local::lib \*(Aq~/foo\*(Aq; # same, but ~/foo \& \& # Or... \& use FindBin; \& use local::lib "$FindBin::Bin/../support"; # app\-local support library .Ve .PP From the shell \- .PP .Vb 2 \& # Install LWP and its missing dependencies to the \*(Aq~/perl5\*(Aq directory \& perl \-MCPAN \-Mlocal::lib \-e \*(AqCPAN::install(LWP)\*(Aq \& \& # Just print out useful shell commands \& $ perl \-Mlocal::lib \& PERL_MB_OPT=\*(Aq\-\-install_base /home/username/perl5\*(Aq; export PERL_MB_OPT; \& PERL_MM_OPT=\*(AqINSTALL_BASE=/home/username/perl5\*(Aq; export PERL_MM_OPT; \& PERL5LIB="/home/username/perl5/lib/perl5"; export PERL5LIB; \& PATH="/home/username/perl5/bin:$PATH"; export PATH; \& PERL_LOCAL_LIB_ROOT="/home/usename/perl5:$PERL_LOCAL_LIB_ROOT"; export PERL_LOCAL_LIB_ROOT; .Ve .PP From a \fI.bash_profile\fR or \fI.bashrc\fR file \- .PP .Vb 1 \& eval "$(perl \-I$HOME/perl5/lib/perl5 \-Mlocal::lib)" .Ve .SS "The bootstrapping technique" .IX Subsection "The bootstrapping technique" A typical way to install local::lib is using what is known as the \&\*(L"bootstrapping\*(R" technique. You would do this if your system administrator hasn't already installed local::lib. In this case, you'll need to install local::lib in your home directory. .PP Even if you do have administrative privileges, you will still want to set up your environment variables, as discussed in step 4. Without this, you would still install the modules into the system \s-1CPAN\s0 installation and also your Perl scripts will not use the lib/ path you bootstrapped with local::lib. .PP By default local::lib installs itself and the \s-1CPAN\s0 modules into ~/perl5. .PP Windows users must also see \*(L"Differences when using this module under Win32\*(R". .IP "1." 4 Download and unpack the local::lib tarball from \s-1CPAN\s0 (search for \*(L"Download\*(R" on the \s-1CPAN\s0 page about local::lib). Do this as an ordinary user, not as root or administrator. Unpack the file in your home directory or in any other convenient location. .IP "2." 4 Run this: .Sp .Vb 1 \& perl Makefile.PL \-\-bootstrap .Ve .Sp If the system asks you whether it should automatically configure as much as possible, you would typically answer yes. .IP "3." 4 Run this: (local::lib assumes you have make installed on your system) .Sp .Vb 1 \& make test && make install .Ve .IP "4." 4 Now we need to setup the appropriate environment variables, so that Perl starts using our newly generated lib/ directory. If you are using bash or any other Bourne shells, you can add this to your shell startup script this way: .Sp .Vb 1 \& echo \*(Aqeval "$(perl \-I$HOME/perl5/lib/perl5 \-Mlocal::lib)"\*(Aq >>~/.bashrc .Ve .Sp If you are using C shell, you can do this as follows: .Sp .Vb 3 \& % echo $SHELL \& /bin/csh \& $ echo \*(Aqeval \`perl \-I$HOME/perl5/lib/perl5 \-Mlocal::lib\`\*(Aq >> ~/.cshrc .Ve .Sp After writing your shell configuration file, be sure to re-read it to get the changed settings into your current shell's environment. Bourne shells use \&\f(CW\*(C`. ~/.bashrc\*(C'\fR for this, whereas C shells use \f(CW\*(C`source ~/.cshrc\*(C'\fR. .PP \fIBootstrapping into an alternate directory\fR .IX Subsection "Bootstrapping into an alternate directory" .PP In order to install local::lib into a directory other than the default, you need to specify the name of the directory when you call bootstrap. Then, when setting up the environment variables, both perl and local::lib must be told the location of the bootstrap directory. The setup process would look as follows: .PP .Vb 4 \& perl Makefile.PL \-\-bootstrap=~/foo \& make test && make install \& echo \*(Aqeval "$(perl \-I$HOME/foo/lib/perl5 \-Mlocal::lib=$HOME/foo)"\*(Aq >>~/.bashrc \& . ~/.bashrc .Ve .PP \fIOther bootstrapping options\fR .IX Subsection "Other bootstrapping options" .PP If you're on a slower machine, or are operating under draconian disk space limitations, you can disable the automatic generation of manpages from \s-1POD\s0 when installing modules by using the \f(CW\*(C`\-\-no\-manpages\*(C'\fR argument when bootstrapping: .PP .Vb 1 \& perl Makefile.PL \-\-bootstrap \-\-no\-manpages .Ve .PP To avoid doing several bootstrap for several Perl module environments on the same account, for example if you use it for several different deployed applications independently, you can use one bootstrapped local::lib installation to install modules in different directories directly this way: .PP .Vb 7 \& cd ~/mydir1 \& perl \-Mlocal::lib=./ \& eval $(perl \-Mlocal::lib=./) ### To set the environment for this shell alone \& printenv ### You will see that ~/mydir1 is in the PERL5LIB \& perl \-MCPAN \-e install ... ### whatever modules you want \& cd ../mydir2 \& ... REPEAT ... .Ve .PP If you use \fI.bashrc\fR to activate a local::lib automatically, the local::lib will be re-enabled in any sub-shells used, overriding adjustments you may have made in the parent shell. To avoid this, you can initialize the local::lib in \&\fI.bash_profile\fR rather than \fI.bashrc\fR, or protect the local::lib invocation with a \f(CW$SHLVL\fR check: .PP .Vb 1 \& [ $SHLVL \-eq 1 ] && eval "$(perl \-I$HOME/perl5/lib/perl5 \-Mlocal::lib)" .Ve .PP If you are working with several \f(CW\*(C`local::lib\*(C'\fR environments, you may want to remove some of them from the current environment without disturbing the others. You can deactivate one environment like this (using bourne sh): .PP .Vb 1 \& eval $(perl \-Mlocal::lib=\-\-deactivate,~/path) .Ve .PP which will generate and run the commands needed to remove \f(CW\*(C`~/path\*(C'\fR from your various search paths. Whichever environment was \fBactivated most recently\fR will remain the target for module installations. That is, if you activate \&\f(CW\*(C`~/path_A\*(C'\fR and then you activate \f(CW\*(C`~/path_B\*(C'\fR, new modules you install will go in \f(CW\*(C`~/path_B\*(C'\fR. If you deactivate \f(CW\*(C`~/path_B\*(C'\fR then modules will be installed into \f(CW\*(C`~/pathA\*(C'\fR \*(-- but if you deactivate \f(CW\*(C`~/path_A\*(C'\fR then they will still be installed in \f(CW\*(C`~/pathB\*(C'\fR because pathB was activated later. .PP You can also ask \f(CW\*(C`local::lib\*(C'\fR to clean itself completely out of the current shell's environment with the \f(CW\*(C`\-\-deactivate\-all\*(C'\fR option. For multiple environments for multiple apps you may need to include a modified version of the \f(CW\*(C`use FindBin\*(C'\fR instructions in the \*(L"In code\*(R" sample above. If you did something like the above, you have a set of Perl modules at \f(CW\*(C`~/mydir1/lib\*(C'\fR. If you have a script at \f(CW\*(C`~/mydir1/scripts/myscript.pl\*(C'\fR, you need to tell it where to find the modules you installed for it at \f(CW\*(C`~/mydir1/lib\*(C'\fR. .PP In \f(CW\*(C`~/mydir1/scripts/myscript.pl\*(C'\fR: .PP .Vb 4 \& use strict; \& use warnings; \& use local::lib "$FindBin::Bin/.."; ### points to ~/mydir1 and local::lib finds lib \& use lib "$FindBin::Bin/../lib"; ### points to ~/mydir1/lib .Ve .PP Put this before any \s-1BEGIN\s0 { ... } blocks that require the modules you installed. .SS "Differences when using this module under Win32" .IX Subsection "Differences when using this module under Win32" To set up the proper environment variables for your current session of \&\f(CW\*(C`CMD.exe\*(C'\fR, you can use this: .PP .Vb 5 \& C:\e>perl \-Mlocal::lib \& set PERL_MB_OPT=\-\-install_base C:\eDOCUME~1\eADMINI~1\eperl5 \& set PERL_MM_OPT=INSTALL_BASE=C:\eDOCUME~1\eADMINI~1\eperl5 \& set PERL5LIB=C:\eDOCUME~1\eADMINI~1\eperl5\elib\eperl5 \& set PATH=C:\eDOCUME~1\eADMINI~1\eperl5\ebin;%PATH% \& \& ### To set the environment for this shell alone \& C:\e>perl \-Mlocal::lib > %TEMP%\etmp.bat && %TEMP%\etmp.bat && del %TEMP%\etmp.bat \& ### instead of $(perl \-Mlocal::lib=./) .Ve .PP If you want the environment entries to persist, you'll need to add them to the Control Panel's System applet yourself or use App::local::lib::Win32Helper. .PP The \*(L"~\*(R" is translated to the user's profile directory (the directory named for the user under \*(L"Documents and Settings\*(R" (Windows \s-1XP\s0 or earlier) or \*(L"Users\*(R" (Windows Vista or later)) unless \f(CW$ENV\fR{\s-1HOME\s0} exists. After that, the home directory is translated to a short name (which means the directory must exist) and the subdirectories are created. .PP \fIPowerShell\fR .IX Subsection "PowerShell" .PP local::lib also supports PowerShell, and can be used with the \&\f(CW\*(C`Invoke\-Expression\*(C'\fR cmdlet. .PP .Vb 1 \& Invoke\-Expression "$(perl \-Mlocal::lib)" .Ve .SH "RATIONALE" .IX Header "RATIONALE" The version of a Perl package on your machine is not always the version you need. Obviously, the best thing to do would be to update to the version you need. However, you might be in a situation where you're prevented from doing this. Perhaps you don't have system administrator privileges; or perhaps you are using a package management system such as Debian, and nobody has yet gotten around to packaging up the version you need. .PP local::lib solves this problem by allowing you to create your own directory of Perl packages downloaded from \s-1CPAN\s0 (in a multi-user system, this would typically be within your own home directory). The existing system Perl installation is not affected; you simply invoke Perl with special options so that Perl uses the packages in your own local package directory rather than the system packages. local::lib arranges things so that your locally installed version of the Perl packages takes precedence over the system installation. .PP If you are using a package management system (such as Debian), you don't need to worry about Debian and \s-1CPAN\s0 stepping on each other's toes. Your local version of the packages will be written to an entirely separate directory from those installed by Debian. .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides a quick, convenient way of bootstrapping a user-local Perl module library located within the user's home directory. It also constructs and prints out for the user the list of environment variables using the syntax appropriate for the user's current shell (as specified by the \f(CW\*(C`SHELL\*(C'\fR environment variable), suitable for directly adding to one's shell configuration file. .PP More generally, local::lib allows for the bootstrapping and usage of a directory containing Perl modules outside of Perl's \f(CW@INC\fR. This makes it easier to ship an application with an app-specific copy of a Perl module, or collection of modules. Useful in cases like when an upstream maintainer hasn't applied a patch to a module of theirs that you need for your application. .PP On import, local::lib sets the following environment variables to appropriate values: .IP "\s-1PERL_MB_OPT\s0" 4 .IX Item "PERL_MB_OPT" .PD 0 .IP "\s-1PERL_MM_OPT\s0" 4 .IX Item "PERL_MM_OPT" .IP "\s-1PERL5LIB\s0" 4 .IX Item "PERL5LIB" .IP "\s-1PATH\s0" 4 .IX Item "PATH" .IP "\s-1PERL_LOCAL_LIB_ROOT\s0" 4 .IX Item "PERL_LOCAL_LIB_ROOT" .PD .PP When possible, these will be appended to instead of overwritten entirely. .PP These values are then available for reference by any code after import. .SH "CREATING A SELF-CONTAINED SET OF MODULES" .IX Header "CREATING A SELF-CONTAINED SET OF MODULES" See lib::core::only for one way to do this \- but note that there are a number of caveats, and the best approach is always to perform a build against a clean perl (i.e. site and vendor as close to empty as possible). .SH "IMPORT OPTIONS" .IX Header "IMPORT OPTIONS" Options are values that can be passed to the \f(CW\*(C`local::lib\*(C'\fR import besides the directory to use. They are specified as \f(CW\*(C`use local::lib \*(Aq\-\-option\*(Aq[, path];\*(C'\fR or \f(CW\*(C`perl \-Mlocal::lib=\-\-option[,path]\*(C'\fR. .SS "\-\-deactivate" .IX Subsection "--deactivate" Remove the chosen path (or the default path) from the module search paths if it was added by \f(CW\*(C`local::lib\*(C'\fR, instead of adding it. .SS "\-\-deactivate\-all" .IX Subsection "--deactivate-all" Remove all directories that were added to search paths by \f(CW\*(C`local::lib\*(C'\fR from the search paths. .SS "\-\-quiet" .IX Subsection "--quiet" Don't output any messages about directories being created. .SS "\-\-always" .IX Subsection "--always" Always add directories to environment variables, ignoring if they are already included. .SS "\-\-shelltype" .IX Subsection "--shelltype" Specify the shell type to use for output. By default, the shell will be detected based on the environment. Should be one of: \f(CW\*(C`bourne\*(C'\fR, \f(CW\*(C`csh\*(C'\fR, \&\f(CW\*(C`cmd\*(C'\fR, or \f(CW\*(C`powershell\*(C'\fR. .SS "\-\-no\-create" .IX Subsection "--no-create" Prevents \f(CW\*(C`local::lib\*(C'\fR from creating directories when activating dirs. This is likely to cause issues on Win32 systems. .SH "CLASS METHODS" .IX Header "CLASS METHODS" .SS "ensure_dir_structure_for" .IX Subsection "ensure_dir_structure_for" .ie n .IP "Arguments: $path" 4 .el .IP "Arguments: \f(CW$path\fR" 4 .IX Item "Arguments: $path" .PD 0 .IP "Return value: None" 4 .IX Item "Return value: None" .PD .PP Attempts to create a local::lib directory, including subdirectories and all required parent directories. Throws an exception on failure. .SS "print_environment_vars_for" .IX Subsection "print_environment_vars_for" .ie n .IP "Arguments: $path" 4 .el .IP "Arguments: \f(CW$path\fR" 4 .IX Item "Arguments: $path" .PD 0 .IP "Return value: None" 4 .IX Item "Return value: None" .PD .PP Prints to standard output the variables listed above, properly set to use the given path as the base directory. .SS "build_environment_vars_for" .IX Subsection "build_environment_vars_for" .ie n .IP "Arguments: $path" 4 .el .IP "Arguments: \f(CW$path\fR" 4 .IX Item "Arguments: $path" .PD 0 .ie n .IP "Return value: %environment_vars" 4 .el .IP "Return value: \f(CW%environment_vars\fR" 4 .IX Item "Return value: %environment_vars" .PD .PP Returns a hash with the variables listed above, properly set to use the given path as the base directory. .SS "setup_env_hash_for" .IX Subsection "setup_env_hash_for" .ie n .IP "Arguments: $path" 4 .el .IP "Arguments: \f(CW$path\fR" 4 .IX Item "Arguments: $path" .PD 0 .IP "Return value: None" 4 .IX Item "Return value: None" .PD .PP Constructs the \f(CW%ENV\fR keys for the given path, by calling \&\*(L"build_environment_vars_for\*(R". .SS "active_paths" .IX Subsection "active_paths" .IP "Arguments: None" 4 .IX Item "Arguments: None" .PD 0 .ie n .IP "Return value: @paths" 4 .el .IP "Return value: \f(CW@paths\fR" 4 .IX Item "Return value: @paths" .PD .PP Returns a list of active \f(CW\*(C`local::lib\*(C'\fR paths, according to the \&\f(CW\*(C`PERL_LOCAL_LIB_ROOT\*(C'\fR environment variable and verified against what is really in \f(CW@INC\fR. .SS "install_base_perl_path" .IX Subsection "install_base_perl_path" .ie n .IP "Arguments: $path" 4 .el .IP "Arguments: \f(CW$path\fR" 4 .IX Item "Arguments: $path" .PD 0 .ie n .IP "Return value: $install_base_perl_path" 4 .el .IP "Return value: \f(CW$install_base_perl_path\fR" 4 .IX Item "Return value: $install_base_perl_path" .PD .PP Returns a path describing where to install the Perl modules for this local library installation. Appends the directories \f(CW\*(C`lib\*(C'\fR and \f(CW\*(C`perl5\*(C'\fR to the given path. .SS "lib_paths_for" .IX Subsection "lib_paths_for" .ie n .IP "Arguments: $path" 4 .el .IP "Arguments: \f(CW$path\fR" 4 .IX Item "Arguments: $path" .PD 0 .ie n .IP "Return value: @lib_paths" 4 .el .IP "Return value: \f(CW@lib_paths\fR" 4 .IX Item "Return value: @lib_paths" .PD .PP Returns the list of paths perl will search for libraries, given a base path. This includes the base path itself, the architecture specific subdirectory, and perl version specific subdirectories. These paths may not all exist. .SS "install_base_bin_path" .IX Subsection "install_base_bin_path" .ie n .IP "Arguments: $path" 4 .el .IP "Arguments: \f(CW$path\fR" 4 .IX Item "Arguments: $path" .PD 0 .ie n .IP "Return value: $install_base_bin_path" 4 .el .IP "Return value: \f(CW$install_base_bin_path\fR" 4 .IX Item "Return value: $install_base_bin_path" .PD .PP Returns a path describing where to install the executable programs for this local library installation. Appends the directory \f(CW\*(C`bin\*(C'\fR to the given path. .SS "installer_options_for" .IX Subsection "installer_options_for" .ie n .IP "Arguments: $path" 4 .el .IP "Arguments: \f(CW$path\fR" 4 .IX Item "Arguments: $path" .PD 0 .ie n .IP "Return value: %installer_env_vars" 4 .el .IP "Return value: \f(CW%installer_env_vars\fR" 4 .IX Item "Return value: %installer_env_vars" .PD .PP Returns a hash of environment variables that should be set to cause installation into the given path. .SS "resolve_empty_path" .IX Subsection "resolve_empty_path" .ie n .IP "Arguments: $path" 4 .el .IP "Arguments: \f(CW$path\fR" 4 .IX Item "Arguments: $path" .PD 0 .ie n .IP "Return value: $base_path" 4 .el .IP "Return value: \f(CW$base_path\fR" 4 .IX Item "Return value: $base_path" .PD .PP Builds and returns the base path into which to set up the local module installation. Defaults to \f(CW\*(C`~/perl5\*(C'\fR. .SS "resolve_home_path" .IX Subsection "resolve_home_path" .ie n .IP "Arguments: $path" 4 .el .IP "Arguments: \f(CW$path\fR" 4 .IX Item "Arguments: $path" .PD 0 .ie n .IP "Return value: $home_path" 4 .el .IP "Return value: \f(CW$home_path\fR" 4 .IX Item "Return value: $home_path" .PD .PP Attempts to find the user's home directory. If no definite answer is available, throws an exception. .SS "resolve_relative_path" .IX Subsection "resolve_relative_path" .ie n .IP "Arguments: $path" 4 .el .IP "Arguments: \f(CW$path\fR" 4 .IX Item "Arguments: $path" .PD 0 .ie n .IP "Return value: $absolute_path" 4 .el .IP "Return value: \f(CW$absolute_path\fR" 4 .IX Item "Return value: $absolute_path" .PD .PP Translates the given path into an absolute path. .SS "resolve_path" .IX Subsection "resolve_path" .ie n .IP "Arguments: $path" 4 .el .IP "Arguments: \f(CW$path\fR" 4 .IX Item "Arguments: $path" .PD 0 .ie n .IP "Return value: $absolute_path" 4 .el .IP "Return value: \f(CW$absolute_path\fR" 4 .IX Item "Return value: $absolute_path" .PD .PP Calls the following in a pipeline, passing the result from the previous to the next, in an attempt to find where to configure the environment for a local library installation: \*(L"resolve_empty_path\*(R", \*(L"resolve_home_path\*(R", \&\*(L"resolve_relative_path\*(R". Passes the given path argument to \&\*(L"resolve_empty_path\*(R" which then returns a result that is passed to \&\*(L"resolve_home_path\*(R", which then has its result passed to \&\*(L"resolve_relative_path\*(R". The result of this final call is returned from \&\*(L"resolve_path\*(R". .SH "OBJECT INTERFACE" .IX Header "OBJECT INTERFACE" .SS "new" .IX Subsection "new" .ie n .IP "Arguments: %attributes" 4 .el .IP "Arguments: \f(CW%attributes\fR" 4 .IX Item "Arguments: %attributes" .PD 0 .ie n .IP "Return value: $local_lib" 4 .el .IP "Return value: \f(CW$local_lib\fR" 4 .IX Item "Return value: $local_lib" .PD .PP Constructs a new \f(CW\*(C`local::lib\*(C'\fR object, representing the current state of \&\f(CW@INC\fR and the relevant environment variables. .SH "ATTRIBUTES" .IX Header "ATTRIBUTES" .SS "roots" .IX Subsection "roots" An arrayref representing active \f(CW\*(C`local::lib\*(C'\fR directories. .SS "inc" .IX Subsection "inc" An arrayref representing \f(CW@INC\fR. .SS "libs" .IX Subsection "libs" An arrayref representing the \s-1PERL5LIB\s0 environment variable. .SS "bins" .IX Subsection "bins" An arrayref representing the \s-1PATH\s0 environment variable. .SS "extra" .IX Subsection "extra" A hashref of extra environment variables (e.g. \f(CW\*(C`PERL_MM_OPT\*(C'\fR and \&\f(CW\*(C`PERL_MB_OPT\*(C'\fR) .SS "no_create" .IX Subsection "no_create" If set, \f(CW\*(C`local::lib\*(C'\fR will not try to create directories when activating them. .SH "OBJECT METHODS" .IX Header "OBJECT METHODS" .SS "clone" .IX Subsection "clone" .ie n .IP "Arguments: %attributes" 4 .el .IP "Arguments: \f(CW%attributes\fR" 4 .IX Item "Arguments: %attributes" .PD 0 .ie n .IP "Return value: $local_lib" 4 .el .IP "Return value: \f(CW$local_lib\fR" 4 .IX Item "Return value: $local_lib" .PD .PP Constructs a new \f(CW\*(C`local::lib\*(C'\fR object based on the existing one, overriding the specified attributes. .SS "activate" .IX Subsection "activate" .ie n .IP "Arguments: $path" 4 .el .IP "Arguments: \f(CW$path\fR" 4 .IX Item "Arguments: $path" .PD 0 .ie n .IP "Return value: $new_local_lib" 4 .el .IP "Return value: \f(CW$new_local_lib\fR" 4 .IX Item "Return value: $new_local_lib" .PD .PP Constructs a new instance with the specified path active. .SS "deactivate" .IX Subsection "deactivate" .ie n .IP "Arguments: $path" 4 .el .IP "Arguments: \f(CW$path\fR" 4 .IX Item "Arguments: $path" .PD 0 .ie n .IP "Return value: $new_local_lib" 4 .el .IP "Return value: \f(CW$new_local_lib\fR" 4 .IX Item "Return value: $new_local_lib" .PD .PP Constructs a new instance with the specified path deactivated. .SS "deactivate_all" .IX Subsection "deactivate_all" .IP "Arguments: None" 4 .IX Item "Arguments: None" .PD 0 .ie n .IP "Return value: $new_local_lib" 4 .el .IP "Return value: \f(CW$new_local_lib\fR" 4 .IX Item "Return value: $new_local_lib" .PD .PP Constructs a new instance with all \f(CW\*(C`local::lib\*(C'\fR directories deactivated. .SS "environment_vars_string" .IX Subsection "environment_vars_string" .ie n .IP "Arguments: [ $shelltype ]" 4 .el .IP "Arguments: [ \f(CW$shelltype\fR ]" 4 .IX Item "Arguments: [ $shelltype ]" .PD 0 .ie n .IP "Return value: $shell_env_string" 4 .el .IP "Return value: \f(CW$shell_env_string\fR" 4 .IX Item "Return value: $shell_env_string" .PD .PP Returns a string to set up the \f(CW\*(C`local::lib\*(C'\fR, meant to be run by a shell. .SS "build_environment_vars" .IX Subsection "build_environment_vars" .IP "Arguments: None" 4 .IX Item "Arguments: None" .PD 0 .ie n .IP "Return value: %environment_vars" 4 .el .IP "Return value: \f(CW%environment_vars\fR" 4 .IX Item "Return value: %environment_vars" .PD .PP Returns a hash with the variables listed above, properly set to use the given path as the base directory. .SS "setup_env_hash" .IX Subsection "setup_env_hash" .IP "Arguments: None" 4 .IX Item "Arguments: None" .PD 0 .IP "Return value: None" 4 .IX Item "Return value: None" .PD .PP Constructs the \f(CW%ENV\fR keys for the given path, by calling \&\*(L"build_environment_vars\*(R". .SS "setup_local_lib" .IX Subsection "setup_local_lib" Constructs the \f(CW%ENV\fR hash using \*(L"setup_env_hash\*(R", and set up \f(CW@INC\fR. .SH "A WARNING ABOUT UNINST=1" .IX Header "A WARNING ABOUT UNINST=1" Be careful about using local::lib in combination with \*(L"make install UNINST=1\*(R". The idea of this feature is that will uninstall an old version of a module before installing a new one. However it lacks a safety check that the old version and the new version will go in the same directory. Used in combination with local::lib, you can potentially delete a globally accessible version of a module while installing the new version in a local place. Only combine \*(L"make install UNINST=1\*(R" and local::lib if you understand these possible consequences. .SH "LIMITATIONS" .IX Header "LIMITATIONS" .IP "\(bu" 4 Directory names with spaces in them are not well supported by the perl toolchain and the programs it uses. Pure-perl distributions should support spaces, but problems are more likely with dists that require compilation. A workaround you can do is moving your local::lib to a directory with spaces \&\fBafter\fR you installed all modules inside your local::lib bootstrap. But be aware that you can't update or install \s-1CPAN\s0 modules after the move. .IP "\(bu" 4 Rather basic shell detection. Right now anything with csh in its name is assumed to be a C shell or something compatible, and everything else is assumed to be Bourne, except on Win32 systems. If the \f(CW\*(C`SHELL\*(C'\fR environment variable is not set, a Bourne-compatible shell is assumed. .IP "\(bu" 4 Kills any existing \s-1PERL_MM_OPT\s0 or \s-1PERL_MB_OPT.\s0 .IP "\(bu" 4 Should probably auto-fixup \s-1CPAN\s0 config if not already done. .IP "\(bu" 4 On \s-1VMS\s0 and MacOS Classic (pre-OS X), local::lib loads File::Spec. This means any File::Spec version installed in the local::lib will be ignored by scripts using local::lib. A workaround for this is using \&\f(CW\*(C`use lib "$local_lib/lib/perl5";\*(C'\fR instead of using \f(CW\*(C`local::lib\*(C'\fR directly. .IP "\(bu" 4 Conflicts with ExtUtils::MakeMaker's \f(CW\*(C`PREFIX\*(C'\fR option. \&\f(CW\*(C`local::lib\*(C'\fR uses the \f(CW\*(C`INSTALL_BASE\*(C'\fR option, as it has more predictable and sane behavior. If something attempts to use the \f(CW\*(C`PREFIX\*(C'\fR option when running a \fIMakefile.PL\fR, ExtUtils::MakeMaker will refuse to run, as the two options conflict. This can be worked around by temporarily unsetting the \&\f(CW\*(C`PERL_MM_OPT\*(C'\fR environment variable. .IP "\(bu" 4 Conflicts with Module::Build's \f(CW\*(C`\-\-prefix\*(C'\fR option. Similar to the previous limitation, but any \f(CW\*(C`\-\-prefix\*(C'\fR option specified will be ignored. This can be worked around by temporarily unsetting the \f(CW\*(C`PERL_MB_OPT\*(C'\fR environment variable. .PP Patches very much welcome for any of the above. .IP "\(bu" 4 On Win32 systems, does not have a way to write the created environment variables to the registry, so that they can persist through a reboot. .SH "TROUBLESHOOTING" .IX Header "TROUBLESHOOTING" If you've configured local::lib to install \s-1CPAN\s0 modules somewhere in to your home directory, and at some point later you try to install a module with \f(CW\*(C`cpan \&\-i Foo::Bar\*(C'\fR, but it fails with an error like: \f(CW\*(C`Warning: You do not have permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64\-linux at /usr/lib64/perl5/5.8.8/Foo/Bar.pm\*(C'\fR and buried within the install log is an error saying \f(CW\*(C`\*(AqINSTALL_BASE\*(Aq is not a known MakeMaker parameter name\*(C'\fR, then you've somehow lost your updated ExtUtils::MakeMaker module. .PP To remedy this situation, rerun the bootstrapping procedure documented above. .PP Then, run \f(CW\*(C`rm \-r ~/.cpan/build/Foo\-Bar*\*(C'\fR .PP Finally, re-run \f(CW\*(C`cpan \-i Foo::Bar\*(C'\fR and it should install without problems. .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" .IP "\s-1SHELL\s0" 4 .IX Item "SHELL" .PD 0 .IP "\s-1COMSPEC\s0" 4 .IX Item "COMSPEC" .PD local::lib looks at the user's \f(CW\*(C`SHELL\*(C'\fR environment variable when printing out commands to add to the shell configuration file. .Sp On Win32 systems, \f(CW\*(C`COMSPEC\*(C'\fR is also examined. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 Perl Advent article, 2011 .SH "SUPPORT" .IX Header "SUPPORT" \&\s-1IRC:\s0 .PP .Vb 1 \& Join #toolchain on irc.perl.org. .Ve .SH "AUTHOR" .IX Header "AUTHOR" Matt S Trout http://www.shadowcat.co.uk/ .PP auto_install fixes kindly sponsored by http://www.takkle.com/ .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" Patches to correctly output commands for csh style shells, as well as some documentation additions, contributed by Christopher Nehren . .PP Doc patches for a custom local::lib directory, more cleanups in the english documentation and a german documentation contributed by Torsten Raudssus . .PP Hans Dieter Pearcey sent in some additional tests for ensuring things will install properly, submitted a fix for the bug causing problems with writing Makefiles during bootstrapping, contributed an example program, and submitted yet another fix to ensure that local::lib can install and bootstrap properly. Many, many thanks! .PP pattern of Freenode \s-1IRC\s0 contributed the beginnings of the Troubleshooting section. Many thanks! .PP Patch to add Win32 support contributed by Curtis Jewell . .PP Warnings for missing \s-1PATH/PERL5LIB\s0 (as when not running interactively) silenced by a patch from Marco Emilio Poleggi. .PP Mark Stosberg provided the code for the now deleted \&'\-\-self\-contained' option. .PP Documentation patches to make win32 usage clearer by David Mertens (run4flat). .PP Brazilian portuguese translation and minor doc patches contributed by Breno G. de Oliveira . .PP Improvements to stacking multiple local::lib dirs and removing them from the environment later on contributed by Andrew Rodland . .PP Patch for Carp version mismatch contributed by Hakim Cassimally . .PP Rewrite of internals and numerous bug fixes and added features contributed by Graham Knop . .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2007 \- 2013 the local::lib \*(L"\s-1AUTHOR\*(R"\s0 and \*(L"\s-1CONTRIBUTORS\*(R"\s0 as listed above. .SH "LICENSE" .IX Header "LICENSE" This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK@O\+ihA@Q@Q Try::Tiny.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Try::Tiny 3" .TH Try::Tiny 3 "2021-11-23" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Try::Tiny \- Minimal try/catch with proper preservation of $@ .SH "VERSION" .IX Header "VERSION" version 0.31 .SH "SYNOPSIS" .IX Header "SYNOPSIS" You can use Try::Tiny's \f(CW\*(C`try\*(C'\fR and \f(CW\*(C`catch\*(C'\fR to expect and handle exceptional conditions, avoiding quirks in Perl and common mistakes: .PP .Vb 6 \& # handle errors with a catch handler \& try { \& die "foo"; \& } catch { \& warn "caught error: $_"; # not $@ \& }; .Ve .PP You can also use it like a standalone \f(CW\*(C`eval\*(C'\fR to catch and ignore any error conditions. Obviously, this is an extreme measure not to be undertaken lightly: .PP .Vb 4 \& # just silence errors \& try { \& die "foo"; \& }; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides bare bones \f(CW\*(C`try\*(C'\fR/\f(CW\*(C`catch\*(C'\fR/\f(CW\*(C`finally\*(C'\fR statements that are designed to minimize common mistakes with eval blocks, and \s-1NOTHING\s0 else. .PP This is unlike TryCatch which provides a nice syntax and avoids adding another call stack layer, and supports calling \f(CW\*(C`return\*(C'\fR from the \f(CW\*(C`try\*(C'\fR block to return from the parent subroutine. These extra features come at a cost of a few dependencies, namely Devel::Declare and Scope::Upper which are occasionally problematic, and the additional catch filtering uses Moose type constraints which may not be desirable either. .PP The main focus of this module is to provide simple and reliable error handling for those having a hard time installing TryCatch, but who still want to write correct \f(CW\*(C`eval\*(C'\fR blocks without 5 lines of boilerplate each time. .PP It's designed to work as correctly as possible in light of the various pathological edge cases (see \*(L"\s-1BACKGROUND\*(R"\s0) and to be compatible with any style of error values (simple strings, references, objects, overloaded objects, etc). .PP If the \f(CW\*(C`try\*(C'\fR block dies, it returns the value of the last statement executed in the \f(CW\*(C`catch\*(C'\fR block, if there is one. Otherwise, it returns \f(CW\*(C`undef\*(C'\fR in scalar context or the empty list in list context. The following examples all assign \f(CW"bar"\fR to \f(CW$x\fR: .PP .Vb 3 \& my $x = try { die "foo" } catch { "bar" }; \& my $x = try { die "foo" } || "bar"; \& my $x = (try { die "foo" }) // "bar"; \& \& my $x = eval { die "foo" } || "bar"; .Ve .PP You can add \f(CW\*(C`finally\*(C'\fR blocks, yielding the following: .PP .Vb 3 \& my $x; \& try { die \*(Aqfoo\*(Aq } finally { $x = \*(Aqbar\*(Aq }; \& try { die \*(Aqfoo\*(Aq } catch { warn "Got a die: $_" } finally { $x = \*(Aqbar\*(Aq }; .Ve .PP \&\f(CW\*(C`finally\*(C'\fR blocks are always executed making them suitable for cleanup code which cannot be handled using local. You can add as many \f(CW\*(C`finally\*(C'\fR blocks to a given \f(CW\*(C`try\*(C'\fR block as you like. .PP Note that adding a \f(CW\*(C`finally\*(C'\fR block without a preceding \f(CW\*(C`catch\*(C'\fR block suppresses any errors. This behaviour is consistent with using a standalone \&\f(CW\*(C`eval\*(C'\fR, but it is not consistent with \f(CW\*(C`try\*(C'\fR/\f(CW\*(C`finally\*(C'\fR patterns found in other programming languages, such as Java, Python, Javascript or C#. If you learned the \f(CW\*(C`try\*(C'\fR/\f(CW\*(C`finally\*(C'\fR pattern from one of these languages, watch out for this. .SH "EXPORTS" .IX Header "EXPORTS" All functions are exported by default using Exporter. .PP If you need to rename the \f(CW\*(C`try\*(C'\fR, \f(CW\*(C`catch\*(C'\fR or \f(CW\*(C`finally\*(C'\fR keyword consider using Sub::Import to get Sub::Exporter's flexibility. .IP "try (&;@)" 4 .IX Item "try (&;@)" Takes one mandatory \f(CW\*(C`try\*(C'\fR subroutine, an optional \f(CW\*(C`catch\*(C'\fR subroutine and \f(CW\*(C`finally\*(C'\fR subroutine. .Sp The mandatory subroutine is evaluated in the context of an \f(CW\*(C`eval\*(C'\fR block. .Sp If no error occurred the value from the first block is returned, preserving list/scalar context. .Sp If there was an error and the second subroutine was given it will be invoked with the error in \f(CW$_\fR (localized) and as that block's first and only argument. .Sp \&\f(CW$@\fR does \fBnot\fR contain the error. Inside the \f(CW\*(C`catch\*(C'\fR block it has the same value it had before the \f(CW\*(C`try\*(C'\fR block was executed. .Sp Note that the error may be false, but if that happens the \f(CW\*(C`catch\*(C'\fR block will still be invoked. .Sp Once all execution is finished then the \f(CW\*(C`finally\*(C'\fR block, if given, will execute. .IP "catch (&;@)" 4 .IX Item "catch (&;@)" Intended to be used in the second argument position of \f(CW\*(C`try\*(C'\fR. .Sp Returns a reference to the subroutine it was given but blessed as \&\f(CW\*(C`Try::Tiny::Catch\*(C'\fR which allows try to decode correctly what to do with this code reference. .Sp .Vb 1 \& catch { ... } .Ve .Sp Inside the \f(CW\*(C`catch\*(C'\fR block the caught error is stored in \f(CW$_\fR, while previous value of \f(CW$@\fR is still available for use. This value may or may not be meaningful depending on what happened before the \f(CW\*(C`try\*(C'\fR, but it might be a good idea to preserve it in an error stack. .Sp For code that captures \f(CW$@\fR when throwing new errors (i.e. Class::Throwable), you'll need to do: .Sp .Vb 1 \& local $@ = $_; .Ve .IP "finally (&;@)" 4 .IX Item "finally (&;@)" .Vb 3 \& try { ... } \& catch { ... } \& finally { ... }; .Ve .Sp Or .Sp .Vb 2 \& try { ... } \& finally { ... }; .Ve .Sp Or even .Sp .Vb 3 \& try { ... } \& finally { ... } \& catch { ... }; .Ve .Sp Intended to be the second or third element of \f(CW\*(C`try\*(C'\fR. \f(CW\*(C`finally\*(C'\fR blocks are always executed in the event of a successful \f(CW\*(C`try\*(C'\fR or if \f(CW\*(C`catch\*(C'\fR is run. This allows you to locate cleanup code which cannot be done via \f(CW\*(C`local()\*(C'\fR e.g. closing a file handle. .Sp When invoked, the \f(CW\*(C`finally\*(C'\fR block is passed the error that was caught. If no error was caught, it is passed nothing. (Note that the \f(CW\*(C`finally\*(C'\fR block does not localize \f(CW$_\fR with the error, since unlike in a \f(CW\*(C`catch\*(C'\fR block, there is no way to know if \f(CW\*(C`$_ == undef\*(C'\fR implies that there were no errors.) In other words, the following code does just what you would expect: .Sp .Vb 11 \& try { \& die_sometimes(); \& } catch { \& # ...code run in case of error \& } finally { \& if (@_) { \& print "The try block died with: @_\en"; \& } else { \& print "The try block ran without error.\en"; \& } \& }; .Ve .Sp \&\fBYou must always do your own error handling in the \f(CB\*(C`finally\*(C'\fB block\fR. \f(CW\*(C`Try::Tiny\*(C'\fR will not do anything about handling possible errors coming from code located in these blocks. .Sp Furthermore \fBexceptions in \f(CB\*(C`finally\*(C'\fB blocks are not trappable and are unable to influence the execution of your program\fR. This is due to limitation of \&\f(CW\*(C`DESTROY\*(C'\fR\-based scope guards, which \f(CW\*(C`finally\*(C'\fR is implemented on top of. This may change in a future version of Try::Tiny. .Sp In the same way \f(CW\*(C`catch()\*(C'\fR blesses the code reference this subroutine does the same except it bless them as \f(CW\*(C`Try::Tiny::Finally\*(C'\fR. .SH "BACKGROUND" .IX Header "BACKGROUND" There are a number of issues with \f(CW\*(C`eval\*(C'\fR. .SS "Clobbering $@" .IX Subsection "Clobbering $@" When you run an \f(CW\*(C`eval\*(C'\fR block and it succeeds, \f(CW$@\fR will be cleared, potentially clobbering an error that is currently being caught. .PP This causes action at a distance, clearing previous errors your caller may have not yet handled. .PP \&\f(CW$@\fR must be properly localized before invoking \f(CW\*(C`eval\*(C'\fR in order to avoid this issue. .PP More specifically, before Perl version 5.14.0 \&\f(CW$@\fR was clobbered at the beginning of the \f(CW\*(C`eval\*(C'\fR, which also made it impossible to capture the previous error before you die (for instance when making exception objects with error stacks). .PP For this reason \f(CW\*(C`try\*(C'\fR will actually set \f(CW$@\fR to its previous value (the one available before entering the \f(CW\*(C`try\*(C'\fR block) in the beginning of the \f(CW\*(C`eval\*(C'\fR block. .SS "Localizing $@ silently masks errors" .IX Subsection "Localizing $@ silently masks errors" Inside an \f(CW\*(C`eval\*(C'\fR block, \f(CW\*(C`die\*(C'\fR behaves sort of like: .PP .Vb 4 \& sub die { \& $@ = $_[0]; \& return_undef_from_eval(); \& } .Ve .PP This means that if you were polite and localized \f(CW$@\fR you can't die in that scope, or your error will be discarded (printing \*(L"Something's wrong\*(R" instead). .PP The workaround is very ugly: .PP .Vb 5 \& my $error = do { \& local $@; \& eval { ... }; \& $@; \& }; \& \& ... \& die $error; .Ve .SS "$@ might not be a true value" .IX Subsection "$@ might not be a true value" This code is wrong: .PP .Vb 3 \& if ( $@ ) { \& ... \& } .Ve .PP because due to the previous caveats it may have been unset. .PP \&\f(CW$@\fR could also be an overloaded error object that evaluates to false, but that's asking for trouble anyway. .PP The classic failure mode (fixed in Perl 5.14.0) is: .PP .Vb 3 \& sub Object::DESTROY { \& eval { ... } \& } \& \& eval { \& my $obj = Object\->new; \& \& die "foo"; \& }; \& \& if ( $@ ) { \& \& } .Ve .PP In this case since \f(CW\*(C`Object::DESTROY\*(C'\fR is not localizing \f(CW$@\fR but still uses \&\f(CW\*(C`eval\*(C'\fR, it will set \f(CW$@\fR to \f(CW""\fR. .PP The destructor is called when the stack is unwound, after \f(CW\*(C`die\*(C'\fR sets \f(CW$@\fR to \&\f(CW"foo at Foo.pm line 42\en"\fR, so by the time \f(CW\*(C`if ( $@ )\*(C'\fR is evaluated it has been cleared by \f(CW\*(C`eval\*(C'\fR in the destructor. .PP The workaround for this is even uglier than the previous ones. Even though we can't save the value of \f(CW$@\fR from code that doesn't localize, we can at least be sure the \f(CW\*(C`eval\*(C'\fR was aborted due to an error: .PP .Vb 2 \& my $failed = not eval { \& ... \& \& return 1; \& }; .Ve .PP This is because an \f(CW\*(C`eval\*(C'\fR that caught a \f(CW\*(C`die\*(C'\fR will always return a false value. .SH "ALTERNATE SYNTAX" .IX Header "ALTERNATE SYNTAX" Using Perl 5.10 you can use \*(L"Switch statements\*(R" in perlsyn (but please don't, because that syntax has since been deprecated because there was too much unexpected magical behaviour). .PP The \f(CW\*(C`catch\*(C'\fR block is invoked in a topicalizer context (like a \f(CW\*(C`given\*(C'\fR block), but note that you can't return a useful value from \f(CW\*(C`catch\*(C'\fR using the \f(CW\*(C`when\*(C'\fR blocks without an explicit \f(CW\*(C`return\*(C'\fR. .PP This is somewhat similar to Perl 6's \f(CW\*(C`CATCH\*(C'\fR blocks. You can use it to concisely match errors: .PP .Vb 6 \& try { \& require Foo; \& } catch { \& when (/^Can\*(Aqt locate .*?\e.pm in \e@INC/) { } # ignore \& default { die $_ } \& }; .Ve .SH "CAVEATS" .IX Header "CAVEATS" .IP "\(bu" 4 \&\f(CW@_\fR is not available within the \f(CW\*(C`try\*(C'\fR block, so you need to copy your argument list. In case you want to work with argument values directly via \f(CW@_\fR aliasing (i.e. allow \f(CW\*(C`$_[1] = "foo"\*(C'\fR), you need to pass \f(CW@_\fR by reference: .Sp .Vb 4 \& sub foo { \& my ( $self, @args ) = @_; \& try { $self\->bar(@args) } \& } .Ve .Sp or .Sp .Vb 5 \& sub bar_in_place { \& my $self = shift; \& my $args = \e@_; \& try { $_ = $self\->bar($_) for @$args } \& } .Ve .IP "\(bu" 4 \&\f(CW\*(C`return\*(C'\fR returns from the \f(CW\*(C`try\*(C'\fR block, not from the parent sub (note that this is also how \f(CW\*(C`eval\*(C'\fR works, but not how TryCatch works): .Sp .Vb 7 \& sub parent_sub { \& try { \& die; \& } \& catch { \& return; \& }; \& \& say "this text WILL be displayed, even though an exception is thrown"; \& } .Ve .Sp Instead, you should capture the return value: .Sp .Vb 6 \& sub parent_sub { \& my $success = try { \& die; \& 1; \& }; \& return unless $success; \& \& say "This text WILL NEVER appear!"; \& } \& # OR \& sub parent_sub_with_catch { \& my $success = try { \& die; \& 1; \& } \& catch { \& # do something with $_ \& return undef; #see note \& }; \& return unless $success; \& \& say "This text WILL NEVER appear!"; \& } .Ve .Sp Note that if you have a \f(CW\*(C`catch\*(C'\fR block, it must return \f(CW\*(C`undef\*(C'\fR for this to work, since if a \f(CW\*(C`catch\*(C'\fR block exists, its return value is returned in place of \f(CW\*(C`undef\*(C'\fR when an exception is thrown. .IP "\(bu" 4 \&\f(CW\*(C`try\*(C'\fR introduces another caller stack frame. Sub::Uplevel is not used. Carp will not report this when using full stack traces, though, because \&\f(CW%Carp::Internal\fR is used. This lack of magic is considered a feature. .IP "\(bu" 4 The value of \f(CW$_\fR in the \f(CW\*(C`catch\*(C'\fR block is not guaranteed to be the value of the exception thrown (\f(CW$@\fR) in the \f(CW\*(C`try\*(C'\fR block. There is no safe way to ensure this, since \f(CW\*(C`eval\*(C'\fR may be used unhygienically in destructors. The only guarantee is that the \f(CW\*(C`catch\*(C'\fR will be called if an exception is thrown. .IP "\(bu" 4 The return value of the \f(CW\*(C`catch\*(C'\fR block is not ignored, so if testing the result of the expression for truth on success, be sure to return a false value from the \f(CW\*(C`catch\*(C'\fR block: .Sp .Vb 4 \& my $obj = try { \& MightFail\->new; \& } catch { \& ... \& \& return; # avoid returning a true value; \& }; \& \& return unless $obj; .Ve .IP "\(bu" 4 \&\f(CW$SIG{_\|_DIE_\|_}\fR is still in effect. .Sp Though it can be argued that \f(CW$SIG{_\|_DIE_\|_}\fR should be disabled inside of \&\f(CW\*(C`eval\*(C'\fR blocks, since it isn't people have grown to rely on it. Therefore in the interests of compatibility, \f(CW\*(C`try\*(C'\fR does not disable \f(CW$SIG{_\|_DIE_\|_}\fR for the scope of the error throwing code. .IP "\(bu" 4 Lexical \f(CW$_\fR may override the one set by \f(CW\*(C`catch\*(C'\fR. .Sp For example Perl 5.10's \f(CW\*(C`given\*(C'\fR form uses a lexical \f(CW$_\fR, creating some confusing behavior: .Sp .Vb 10 \& given ($foo) { \& when (...) { \& try { \& ... \& } catch { \& warn $_; # will print $foo, not the error \& warn $_[0]; # instead, get the error like this \& } \& } \& } .Ve .Sp Note that this behavior was changed once again in Perl5 version 18 . However, since the entirety of lexical \f(CW$_\fR is now considered experimental , it is unclear whether the new version 18 behavior is final. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "Syntax::Keyword::Try" 4 .IX Item "Syntax::Keyword::Try" Only available on perls >= 5.14, with a slightly different syntax (e.g. no trailing \f(CW\*(C`;\*(C'\fR because it's actually a keyword, not a sub, but this means you can \f(CW\*(C`return\*(C'\fR and \f(CW\*(C`next\*(C'\fR within it). Use Feature::Compat::Try to automatically switch to the native \f(CW\*(C`try\*(C'\fR syntax in newer perls (when available). See also Try Catch Exception Handling. .IP "TryCatch" 4 .IX Item "TryCatch" Much more feature complete, more convenient semantics, but at the cost of implementation complexity. .IP "autodie" 4 .IX Item "autodie" Automatic error throwing for builtin functions and more. Also designed to work well with \f(CW\*(C`given\*(C'\fR/\f(CW\*(C`when\*(C'\fR. .IP "Throwable" 4 .IX Item "Throwable" A lightweight role for rolling your own exception classes. .IP "Error" 4 .IX Item "Error" Exception object implementation with a \f(CW\*(C`try\*(C'\fR statement. Does not localize \&\f(CW$@\fR. .IP "Exception::Class::TryCatch" 4 .IX Item "Exception::Class::TryCatch" Provides a \f(CW\*(C`catch\*(C'\fR statement, but properly calling \f(CW\*(C`eval\*(C'\fR is your responsibility. .Sp The \f(CW\*(C`try\*(C'\fR keyword pushes \f(CW$@\fR onto an error stack, avoiding some of the issues with \f(CW$@\fR, but you still need to localize to prevent clobbering. .SH "LIGHTNING TALK" .IX Header "LIGHTNING TALK" I gave a lightning talk about this module, you can see the slides (Firefox only): .PP .PP Or read the source: .PP .SH "SUPPORT" .IX Header "SUPPORT" Bugs may be submitted through the \s-1RT\s0 bug tracker (or bug\-Try\-Tiny@rt.cpan.org ). .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 יובל קוג'מן (Yuval Kogman) .IP "\(bu" 4 Jesse Luehrs .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Karen Etheridge .IP "\(bu" 4 Peter Rabbitson .IP "\(bu" 4 Ricardo Signes .IP "\(bu" 4 Mark Fowler .IP "\(bu" 4 Graham Knop .IP "\(bu" 4 Aristotle Pagaltzis .IP "\(bu" 4 Dagfinn Ilmari Mannsåker .IP "\(bu" 4 Lukas Mai .IP "\(bu" 4 Alex .IP "\(bu" 4 anaxagoras .IP "\(bu" 4 Andrew Yates .IP "\(bu" 4 awalker .IP "\(bu" 4 chromatic .IP "\(bu" 4 cm-perl .IP "\(bu" 4 David Lowe .IP "\(bu" 4 Glenn Fowler .IP "\(bu" 4 Hans Dieter Pearcey .IP "\(bu" 4 Jens Berthold .IP "\(bu" 4 Jonathan Yu .IP "\(bu" 4 Marc Mims .IP "\(bu" 4 Mark Stosberg .IP "\(bu" 4 Pali .IP "\(bu" 4 Paul Howarth .IP "\(bu" 4 Rudolf Leermakers .SH "COPYRIGHT AND LICENCE" .IX Header "COPYRIGHT AND LICENCE" This software is Copyright (c) 2009 by יובל קוג'מן (Yuval Kogman). .PP This is free software, licensed under: .PP .Vb 1 \& The MIT (X11) License .Ve PK@O\>DKvKvversion::Internals.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "version::Internals 3" .TH version::Internals 3 "2022-07-15" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" version::Internals \- Perl extension for Version Objects .SH "DESCRIPTION" .IX Header "DESCRIPTION" Overloaded version objects for all modern versions of Perl. This documents the internal data representation and underlying code for version.pm. See \&\fIversion.pod\fR for daily usage. This document is only useful for users interested in the gory details. .SH "WHAT IS A VERSION?" .IX Header "WHAT IS A VERSION?" For the purposes of this module, a version \*(L"number\*(R" 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 \*(L"version as number\*(R" that is discussed in the various editions of the Camel book. .PP There are actually two distinct kinds of version objects: .IP "Decimal versions" 4 .IX Item "Decimal versions" Any version which \*(L"looks like a number\*(R", see \*(L"Decimal Versions\*(R". This also includes versions with a single decimal point and a single embedded underscore, see \*(L"Alpha Versions\*(R", even though these must be quoted to preserve the underscore formatting. .IP "Dotted-Decimal versions" 4 .IX Item "Dotted-Decimal versions" Also referred to as \*(L"Dotted-Integer\*(R", these contains more than one decimal point and may have an optional embedded underscore, see Dotted-Decimal Versions. This is what is commonly used in most open source software as the \*(L"external\*(R" 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. .PP Both of these methods will produce similar version objects, in that the default stringification will yield the version \*(L"Normal Form\*(R" only if required: .PP .Vb 3 \& $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 .Ve .PP In specific, version numbers initialized as \*(L"Decimal Versions\*(R" will stringify as they were originally created (i.e. the same string that was passed to \f(CW\*(C`new()\*(C'\fR. Version numbers initialized as \*(L"Dotted-Decimal Versions\*(R" will be stringified as \*(L"Normal Form\*(R". .SS "Decimal Versions" .IX Subsection "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 \&\f(CW$VERSION\fR scalar. A Decimal version is initialized with what looks like a floating point number. Leading zeros \fBare\fR 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: .PP .Vb 7 \& # 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 .Ve .PP 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\*(R". .PP \&\s-1IMPORTANT NOTE:\s0 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. .SS "Dotted-Decimal Versions" .IX Subsection "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. .PP Unlike \*(L"Decimal Versions\*(R", Dotted-Decimal Versions have more than a single decimal point, e.g.: .PP .Vb 6 \& # 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 .Ve .PP In general, Dotted-Decimal Versions permit the greatest amount of freedom to specify a version, whereas Decimal Versions enforce a certain uniformity. .PP Just like \*(L"Decimal Versions\*(R", Dotted-Decimal Versions can be used as \&\*(L"Alpha Versions\*(R". .SS "Alpha Versions" .IX Subsection "Alpha Versions" For module authors using \s-1CPAN,\s0 the convention has been to note unstable releases with an underscore in the version string. (See \s-1CPAN\s0.) 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: .PP .Vb 2 \& # 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"); .Ve .PP Note that you \fBmust\fR 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. .SS "Regular Expressions for Version Parsing" .IX Subsection "Regular Expressions for Version Parsing" A formalized definition of the legal forms for version strings is included in the \f(CW\*(C`version::regex\*(C'\fR class. 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): .ie n .IP "$version::LAX" 4 .el .IP "\f(CW$version::LAX\fR" 4 .IX Item "$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. .Sp For dotted decimals: .Sp .Vb 3 \& v1.2 \& 1.2345.6 \& v1.23_4 .Ve .Sp 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). .Sp For decimal versions: .Sp .Vb 3 \& 1 \& 1.2345 \& 1.2345_01 .Ve .Sp 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. .ie n .IP "$version::STRICT" 4 .el .IP "\f(CW$version::STRICT\fR" 4 .IX Item "$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. .RS 4 .IP "v1.234.5" 4 .IX 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. .IP "2.3456" 4 .IX 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. .RE .RS 4 .RE .PP 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: .PP .Vb 6 \& ($pkg, $ver) =~ / \& ^[ \et]* \& use [ \et]+($PKGNAME) \& (?:[ \et]+($version::STRICT))? \& [ \et]*; \& /x; .Ve .PP This would match a line of the form: .PP .Vb 1 \& use Foo::Bar::Baz v1.2.3; # legal only in Perl 5.8.1+ .Ve .PP where \f(CW$PKGNAME\fR is another regular expression that defines the legal forms for package names. .SH "IMPLEMENTATION DETAILS" .IX Header "IMPLEMENTATION DETAILS" .SS "Equivalence between Decimal and Dotted-Decimal Versions" .IX Subsection "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: .PP .Vb 2 \& 5.6.0 == 5.006000 \& 5.005_04 == 5.5.40 .Ve .PP 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, \&\fBplus\fR enough trailing zeros to reach the next multiple of three. .PP This was the method that version.pm adopted as well. Some examples may be helpful: .PP .Vb 9 \& 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 .Ve .SS "Quoting Rules" .IX Subsection "Quoting Rules" Because of the nature of the Perl parsing and tokenizing routines, certain initialization values \fBmust\fR be quoted in order to correctly parse as the intended version, especially when using the \f(CW\*(C`declare\*(C'\fR or \&\*(L"\fBqv()\fR\*(R" methods. While you do not have to quote decimal numbers when creating version objects, it is always safe to quote \fBall\fR initial values when using version.pm methods, as this will ensure that what you type is what is used. .PP Additionally, if you quote your initializer, then the quoted value that goes \&\fBin\fR will be exactly what comes \fBout\fR when your \f(CW$VERSION\fR 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. .PP 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: .PP .Vb 4 \& $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 .Ve .PP 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: .PP .Vb 2 \& $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 .Ve .SS "What about v\-strings?" .IX Subsection "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: .PP .Vb 2 \& $vs1 = 1.2.3; # encoded as \e1\e2\e3 \& $vs2 = v1.2; # encoded as \e1\e2 .Ve .PP However, the use of bare v\-strings to initialize version objects is \&\fBstrongly\fR discouraged in all circumstances. Also, bare v\-strings are not completely supported in any version of Perl prior to 5.8.1. .PP If you insist on using bare v\-strings with Perl > 5.6.0, be aware of the following limitations: .PP 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 \fBmust\fR use a three part version, e.g. 1.2.3 or v1.2.3 in order for this heuristic to be successful. .PP 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. .PP 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. .SS "Version Object Internals" .IX Subsection "Version Object Internals" version.pm provides an overloaded version object that is designed to both encapsulate the author's intended \f(CW$VERSION\fR 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 overload methods to simplify code that needs to compare, print, etc the objects. .PP The internal structure of version objects is a blessed hash with several components: .PP .Vb 11 \& bless( { \& \*(Aqoriginal\*(Aq => \*(Aqv1.2.3_4\*(Aq, \& \*(Aqalpha\*(Aq => 1, \& \*(Aqqv\*(Aq => 1, \& \*(Aqversion\*(Aq => [ \& 1, \& 2, \& 3, \& 4 \& ] \& }, \*(Aqversion\*(Aq ); .Ve .IP "original" 4 .IX 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 \&\fB\s-1STRONGLY\s0\fR discouraged, in that it will confuse you and your users. .IP "qv" 4 .IX Item "qv" A boolean that denotes whether this is a decimal or dotted-decimal version. See \*(L"\fBis_qv()\fR\*(R" in version. .IP "alpha" 4 .IX Item "alpha" A boolean that denotes whether this is an alpha version. \s-1NOTE:\s0 that the underscore can only appear in the last position. See \*(L"\fBis_alpha()\fR\*(R" in version. .IP "version" 4 .IX Item "version" An array of non-negative integers that is used for comparison purposes with other version objects. .SS "Replacement \s-1UNIVERSAL::VERSION\s0" .IX Subsection "Replacement UNIVERSAL::VERSION" In addition to the version objects, this modules also replaces the core \&\s-1UNIVERSAL::VERSION\s0 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. .PP For example: .PP .Vb 2 \& package Foo; \& $VERSION = 1.2; \& \& package Bar; \& $VERSION = "v1.3.5"; # works with all Perl\*(Aqs (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..." .Ve .PP \&\s-1IMPORTANT NOTE:\s0 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 \&\f(CW\*(C`use\*(C'\fR or \f(CW\*(C`require\*(C'\fR, rather than manually poking at \f(CW\*(C`class\->VERSION\*(C'\fR and then doing a comparison yourself. .PP The replacement \s-1UNIVERSAL::VERSION,\s0 when used as a function, like this: .PP .Vb 1 \& print $module\->VERSION; .Ve .PP will also exclusively return the stringified form. See \*(L"Stringification\*(R" for more details. .SH "USAGE DETAILS" .IX Header "USAGE DETAILS" .SS "Using modules that use version.pm" .IX Subsection "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 \&\f(CW$VERSION\fR 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: .PP .Vb 4 \& package Example; \& use version; $VERSION = qv(\*(Aq1.2.2\*(Aq); \& ...module code here... \& 1; .Ve .IP "Decimal versions always work" 4 .IX Item "Decimal versions always work" Code of the form: .Sp .Vb 1 \& use Example 1.002003; .Ve .Sp will always work correctly. The \f(CW\*(C`use\*(C'\fR will perform an automatic \&\f(CW$VERSION\fR 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: .Sp .Vb 1 \& Example version 1.002003 (v1.2.3) required\-\-this is only version 1.002002 (v1.2.2)... .Ve .IP "Dotted-Decimal version work sometimes" 4 .IX Item "Dotted-Decimal version work sometimes" With Perl >= 5.6.2, you can also use a line like this: .Sp .Vb 1 \& use Example 1.2.3; .Ve .Sp 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?\*(R" above). This has to do with that fact that \f(CW\*(C`use\*(C'\fR only checks to see if the second term \fIlooks like a number\fR and passes that to the replacement \s-1UNIVERSAL::VERSION\s0. This is not true in Perl 5.005_04, however, so you are \fBstrongly encouraged\fR to always use a Decimal version in your code, even for those versions of Perl which support the Dotted-Decimal version. .SS "Object Methods" .IX Subsection "Object Methods" .IP "\fBnew()\fR" 4 .IX Item "new()" Like many \s-1OO\s0 interfaces, the \fBnew()\fR method is used to initialize version objects. If two arguments are passed to \f(CW\*(C`new()\*(C'\fR, the \fBsecond\fR one will be used as if it were prefixed with \*(L"v\*(R". This is to support historical use of the \&\f(CW\*(C`qw\*(C'\fR operator with the \s-1CVS\s0 variable \f(CW$Revision\fR, which is automatically incremented by \s-1CVS\s0 every time the file is committed to the repository. .Sp In order to facilitate this feature, the following code can be employed: .Sp .Vb 1 \& $VERSION = version\->new(qw$Revision: 2.7 $); .Ve .Sp and the version object will be created as if the following code were used: .Sp .Vb 1 \& $VERSION = version\->new("v2.7"); .Ve .Sp In other words, the version will be automatically parsed out of the string, and it will be quoted to preserve the meaning \s-1CVS\s0 normally carries for versions. The \s-1CVS\s0 \f(CW$Revision\fR$ 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. .Sp A new version object can be created as a copy of an existing version object, either as a class method: .Sp .Vb 2 \& $v1 = version\->new(12.3); \& $v2 = version\->new($v1); .Ve .Sp or as an object method: .Sp .Vb 2 \& $v1 = version\->new(12.3); \& $v2 = $v1\->new(12.3); .Ve .Sp and in each case, \f(CW$v1\fR and \f(CW$v2\fR will be identical. \s-1NOTE:\s0 if you create a new object using an existing object like this: .Sp .Vb 1 \& $v2 = $v1\->new(); .Ve .Sp the new object \fBwill not\fR be a clone of the existing object. In the example case, \f(CW$v2\fR will be an empty object of the same type as \f(CW$v1\fR. .IP "\fBqv()\fR" 4 .IX Item "qv()" An alternate way to create a new version object is through the exported \&\fBqv()\fR 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: .Sp .Vb 2 \& $v1 = qv(1.2); # v1.2.0 \& $v2 = qv("1.2"); # also v1.2.0 .Ve .Sp 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 \fBqv()\fR be quoted strings instead of bare numbers. .Sp To prevent the \f(CW\*(C`qv()\*(C'\fR function from being exported to the caller's namespace, either use version with a null parameter: .Sp .Vb 1 \& use version (); .Ve .Sp or just require version, like this: .Sp .Vb 1 \& require version; .Ve .Sp Both methods will prevent the \fBimport()\fR method from firing and exporting the \&\f(CW\*(C`qv()\*(C'\fR sub. .PP For the subsequent examples, the following three objects will be used: .PP .Vb 3 \& $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" .Ve .IP "Normal Form" 4 .IX 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 \fBqv()\fR operator, the stringified representation is returned in a normalized or reduced form (no extraneous zeros), and with a leading 'v': .Sp .Vb 6 \& 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" .Ve .Sp 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: .Sp .Vb 3 \& my $newver = version\->new($ver\->stringify); \& if ($newver eq $ver ) # always true \& {...} .Ve .IP "Numification" 4 .IX 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 \f(CW$obj\fR\->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: .Sp .Vb 2 \& print $ver\->numify; # prints 1.002003004 \& print $nver\->numify; # prints 1.002 .Ve .Sp Unlike the stringification operator, there is never any need to append trailing zeros to preserve the correct version value. .IP "Stringification" 4 .IX Item "Stringification" The default stringification for version objects returns exactly the same string as was used to create it, whether you used \f(CW\*(C`new()\*(C'\fR or \f(CW\*(C`qv()\*(C'\fR, with one exception. The sole exception is if the object was created using \&\f(CW\*(C`qv()\*(C'\fR 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. .Sp For example: .Sp .Vb 7 \& 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 .Ve .Sp See also \s-1UNIVERSAL::VERSION\s0, as this also returns the stringified form when used as a class method. .Sp \&\s-1IMPORTANT NOTE:\s0 There is one exceptional cases shown in the above table where the \*(L"initializer\*(R" is not stringwise equivalent to the stringified representation. If you use the \f(CW\*(C`qv\*(C'\fR() operator on a version without a leading 'v' \fBand\fR with only a single decimal place, the stringified output will have a leading 'v', to preserve the sense. See the \*(L"\fBqv()\fR\*(R" operator for more details. .Sp \&\s-1IMPORTANT NOTE 2:\s0 Attempting to bypass the normal stringification rules by manually applying \fBnumify()\fR and \fBnormal()\fR will sometimes yield surprising results: .Sp .Vb 1 \& print version\->new(version\->new("v1.0")\->numify)\->normal; # v1.0.0 .Ve .Sp The reason for this is that the \fBnumify()\fR operator will turn \*(L"v1.0\*(R" into the equivalent string \*(L"1.000000\*(R". Forcing the outer version object to \fBnormal()\fR form will display the mathematically equivalent \*(L"v1.0.0\*(R". .Sp As the example in \*(L"\fBnew()\fR\*(R" shows, you can always create a copy of an existing version object with the same value by the very compact: .Sp .Vb 1 \& $v2 = $v1\->new($v1); .Ve .Sp and be assured that both \f(CW$v1\fR and \f(CW$v2\fR will be completely equivalent, down to the same internal representation as well as stringification. .IP "Comparison operators" 4 .IX Item "Comparison operators" Both \f(CW\*(C`cmp\*(C'\fR and \f(CW\*(C`<=>\*(C'\fR 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 \*(L"v1.2\*(R" and \*(L"1.2.0\*(R" will compare as identical. .Sp For example, the following relations hold: .Sp .Vb 7 \& 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 .Ve .Sp It is probably best to chose either the Decimal notation or the string notation and stick with it, to reduce confusion. Perl6 version objects \&\fBmay\fR only support Decimal comparisons. See also \*(L"Quoting Rules\*(R". .Sp \&\s-1WARNING:\s0 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: .Sp .Vb 2 \& 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 .Ve .Sp For this reason, it is best to use either exclusively \*(L"Decimal Versions\*(R" or \&\*(L"Dotted-Decimal Versions\*(R" with multiple decimal points. .IP "Logical Operators" 4 .IX Item "Logical Operators" If you need to test whether a version object has been initialized, you can simply test it directly: .Sp .Vb 2 \& $vobj = version\->new($something); \& if ( $vobj ) # true only if $something was non\-blank .Ve .Sp 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: .Sp .Vb 3 \& $vobj = version\->new("1.2_3"); # MUST QUOTE \& ...later... \& if ( $vobj\->is_alpha ) # True .Ve .SH "AUTHOR" .IX Header "AUTHOR" John Peacock .SH "SEE ALSO" .IX Header "SEE ALSO" perl. PK@O\?&&CPAN::Admin.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::Admin 3" .TH CPAN::Admin 3 "2018-11-27" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" .Vb 1 \& CPAN::Admin \- A CPAN Shell for CPAN admins .Ve .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& perl \-MCPAN::Admin \-e shell .Ve .SH "STATUS" .IX Header "STATUS" Note: this module is currently not maintained. If you need it and fix it for your needs, please submit patches. .SH "DESCRIPTION" .IX Header "DESCRIPTION" CPAN::Admin is a subclass of \s-1CPAN\s0 that adds the commands \f(CW\*(C`register\*(C'\fR and \f(CW\*(C`modsearch\*(C'\fR to the \s-1CPAN\s0 shell. .PP \&\f(CW\*(C`register\*(C'\fR calls \f(CW\*(C`get\*(C'\fR on the named module, assembles a couple of informations (description, language), and calls Netscape with the \&\-remote argument so that a form is filled with all the assembled informations and the registration can be performed with a single click. If the command line has more than one argument, register does not run a \f(CW\*(C`get\*(C'\fR, instead it interprets the rest of the line as \s-1DSLI\s0 status, description, and userid and sends them to netscape such that the form is again mostly filled and can be edited or confirmed with a single click. CPAN::Admin never performs the submission click for you, it is only intended to fill in the form on \s-1PAUSE\s0 and leave the confirmation to you. .PP \&\f(CW\*(C`modsearch\*(C'\fR simply passes the arguments to the search engine for the modules@perl.org mailing list at where all registration requests are stored. It does so in the same way as register, namely with the \f(CW\*(C`netscape \-remote\*(C'\fR command. .PP An experimental feature has also been added, namely to color already registered modules in listings. If you have Term::ANSIColor installed, the u, r, and m commands will show already registered modules in green. .SH "PREREQUISITES" .IX Header "PREREQUISITES" URI::Escape, a browser available in the path, the browser must understand the \-remote switch (as far as I know, this is only available on \s-1UNIX\s0); coloring of registered modules is only available if Term::ANSIColor is installed. .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK@O\ m mCPAN::FirstTime.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::FirstTime 3" .TH CPAN::FirstTime 3 "2022-04-03" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::FirstTime \- Utility for CPAN::Config file Initialization .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBCPAN::FirstTime::init()\fR .SH "DESCRIPTION" .IX Header "DESCRIPTION" The init routine asks a few questions and writes a CPAN/Config.pm or CPAN/MyConfig.pm file (depending on what it is currently using). .PP In the following all questions and explanations regarding config variables are collected. .IP "allow_installing_module_downgrades" 2 .IX Item "allow_installing_module_downgrades" The \s-1CPAN\s0 shell can watch the \f(CW\*(C`blib/\*(C'\fR directories that are built up before running \f(CW\*(C`make test\*(C'\fR to determine whether the current distribution will end up with modules being overwritten with decreasing module version numbers. It can then let the build of this distro fail when it discovers a downgrade. .Sp Do you want to allow installing distros with decreasing module versions compared to what you have installed (yes, no, ask/yes, ask/no)? .IP "allow_installing_outdated_dists" 2 .IX Item "allow_installing_outdated_dists" The \s-1CPAN\s0 shell can watch the \f(CW\*(C`blib/\*(C'\fR directories that are built up before running \f(CW\*(C`make test\*(C'\fR to determine whether the current distribution contains modules that are indexed with a distro with a higher distro-version number than the current one. It can then let the build of this distro fail when it would not represent the most up-to-date version of the distro. .Sp Note: choosing anything but 'yes' for this option will need CPAN::DistnameInfo being installed for taking effect. .Sp Do you want to allow installing distros that are not indexed as the highest distro-version for all contained modules (yes, no, ask/yes, ask/no)? .IP "auto_commit" 2 .IX Item "auto_commit" Normally \s-1CPAN\s0.pm keeps config variables in memory and changes need to be saved in a separate 'o conf commit' command to make them permanent between sessions. If you set the 'auto_commit' option to true, changes to a config variable are always automatically committed to disk. .Sp Always commit changes to config variables to disk? .IP "build_cache" 2 .IX Item "build_cache" \&\s-1CPAN\s0.pm can limit the size of the disk area for keeping the build directories with all the intermediate files. .Sp Cache size for build directory (in \s-1MB\s0)? .IP "build_dir" 2 .IX Item "build_dir" Directory where the build process takes place? .IP "build_dir_reuse" 2 .IX Item "build_dir_reuse" Until version 1.88 \s-1CPAN\s0.pm never trusted the contents of the build_dir directory between sessions. Since 1.88_58 \s-1CPAN\s0.pm has a YAML-based mechanism that makes it possible to share the contents of the build_dir/ directory between different sessions with the same version of perl. People who prefer to test things several days before installing will like this feature because it saves a lot of time. .Sp If you say yes to the following question, \s-1CPAN\s0 will try to store enough information about the build process so that it can pick up in future sessions at the same state of affairs as it left a previous session. .Sp Store and re-use state information about distributions between \&\s-1CPAN\s0.pm sessions? .IP "build_requires_install_policy" 2 .IX Item "build_requires_install_policy" When a module declares another one as a 'build_requires' prerequisite this means that the other module is only needed for building or testing the module but need not be installed permanently. In this case you may wish to install that other module nonetheless or just keep it in the 'build_dir' directory to have it available only temporarily. Installing saves time on future installations but makes the perl installation bigger. .Sp You can choose if you want to always install (yes), never install (no) or be always asked. In the latter case you can set the default answer for the question to yes (ask/yes) or no (ask/no). .Sp Policy on installing 'build_requires' modules (yes, no, ask/yes, ask/no)? .IP "cache_metadata" 2 .IX Item "cache_metadata" To considerably speed up the initial \s-1CPAN\s0 shell startup, it is possible to use Storable to create a cache of metadata. If Storable is not available, the normal index mechanism will be used. .Sp Note: this mechanism is not used when use_sqlite is on and SQLite is running. .Sp Cache metadata (yes/no)? .IP "check_sigs" 2 .IX Item "check_sigs" \&\s-1CPAN\s0 packages can be digitally signed by authors and thus verified with the security provided by strong cryptography. The exact mechanism is defined in the Module::Signature module. While this is generally considered a good thing, it is not always convenient to the end user to install modules that are signed incorrectly or where the key of the author is not available or where some prerequisite for Module::Signature has a bug and so on. .Sp With the check_sigs parameter you can turn signature checking on and off. The default is off for now because the whole tool chain for the functionality is not yet considered mature by some. The author of \&\s-1CPAN\s0.pm would recommend setting it to true most of the time and turning it off only if it turns out to be annoying. .Sp Note that if you do not have Module::Signature installed, no signature checks will be performed at all. .Sp Always try to check and verify signatures if a \s-1SIGNATURE\s0 file is in the package and Module::Signature is installed (yes/no)? .IP "cleanup_after_install" 2 .IX Item "cleanup_after_install" Users who install modules and do not intend to look back, can free occupied disk space quickly by letting \s-1CPAN\s0.pm cleanup each build directory immediately after a successful install. .Sp Remove build directory after a successful install? (yes/no)? .IP "colorize_output" 2 .IX Item "colorize_output" When you have Term::ANSIColor installed, you can turn on colorized output to have some visual differences between normal \s-1CPAN\s0.pm output, warnings, debugging output, and the output of the modules being installed. Set your favorite colors after some experimenting with the Term::ANSIColor module. .Sp Please note that on Windows platforms colorized output also requires the Win32::Console::ANSI module. .Sp Do you want to turn on colored output? .IP "colorize_print" 2 .IX Item "colorize_print" Color for normal output? .IP "colorize_warn" 2 .IX Item "colorize_warn" Color for warnings? .IP "colorize_debug" 2 .IX Item "colorize_debug" Color for debugging messages? .IP "commandnumber_in_prompt" 2 .IX Item "commandnumber_in_prompt" The prompt of the cpan shell can contain the current command number for easier tracking of the session or be a plain string. .Sp Do you want the command number in the prompt (yes/no)? .IP "connect_to_internet_ok" 2 .IX Item "connect_to_internet_ok" If you have never defined your own \f(CW\*(C`urllist\*(C'\fR in your configuration then \f(CW\*(C`CPAN.pm\*(C'\fR will be hesitant to use the built in default sites for downloading. It will ask you once per session if a connection to the internet is \s-1OK\s0 and only if you say yes, it will try to connect. But to avoid this question, you can choose your favorite download sites once and get away with it. Or, if you have no favorite download sites answer yes to the following question. .Sp If no urllist has been chosen yet, would you prefer \s-1CPAN\s0.pm to connect to the built-in default sites without asking? (yes/no)? .IP "ftp_passive" 2 .IX Item "ftp_passive" Shall we always set the \s-1FTP_PASSIVE\s0 environment variable when dealing with ftp download (yes/no)? .IP "ftpstats_period" 2 .IX Item "ftpstats_period" Statistics about downloads are truncated by size and period simultaneously. .Sp How many days shall we keep statistics about downloads? .IP "ftpstats_size" 2 .IX Item "ftpstats_size" Statistics about downloads are truncated by size and period simultaneously. Setting this to zero or negative disables download statistics. .Sp How many items shall we keep in the statistics about downloads? .IP "getcwd" 2 .IX Item "getcwd" \&\s-1CPAN\s0.pm changes the current working directory often and needs to determine its own current working directory. Per default it uses Cwd::cwd but if this doesn't work on your system for some reason, alternatives can be configured according to the following table: .Sp .Vb 5 \& cwd Cwd::cwd \& getcwd Cwd::getcwd \& fastcwd Cwd::fastcwd \& getdcwd Cwd::getdcwd \& backtickcwd external command cwd .Ve .Sp Preferred method for determining the current working directory? .IP "halt_on_failure" 2 .IX Item "halt_on_failure" Normally, \s-1CPAN\s0.pm continues processing the full list of targets and dependencies, even if one of them fails. However, you can specify that \s-1CPAN\s0 should halt after the first failure. (Note that optional recommended or suggested modules that fail will not cause a halt.) .Sp Do you want to halt on failure (yes/no)? .IP "histfile" 2 .IX Item "histfile" If you have one of the readline packages (Term::ReadLine::Perl, Term::ReadLine::Gnu, possibly others) installed, the interactive \s-1CPAN\s0 shell will have history support. The next two questions deal with the filename of the history file and with its size. If you do not want to set this variable, please hit \s-1SPACE ENTER\s0 to the following question. .Sp File to save your history? .IP "histsize" 2 .IX Item "histsize" Number of lines to save? .IP "inactivity_timeout" 2 .IX Item "inactivity_timeout" Sometimes you may wish to leave the processes run by \s-1CPAN\s0 alone without caring about them. Because the Makefile.PL or the Build.PL sometimes contains question you're expected to answer, you can set a timer that will kill a 'perl Makefile.PL' process after the specified time in seconds. .Sp If you set this value to 0, these processes will wait forever. This is the default and recommended setting. .Sp Timeout for inactivity during {Makefile,Build}.PL? .IP "index_expire" 2 .IX Item "index_expire" The \s-1CPAN\s0 indexes are usually rebuilt once or twice per hour, but the typical \s-1CPAN\s0 mirror mirrors only once or twice per day. Depending on the quality of your mirror and your desire to be on the bleeding edge, you may want to set the following value to more or less than one day (which is the default). It determines after how many days \s-1CPAN\s0.pm downloads new indexes. .Sp Let the index expire after how many days? .IP "inhibit_startup_message" 2 .IX Item "inhibit_startup_message" When the \s-1CPAN\s0 shell is started it normally displays a greeting message that contains the running version and the status of readline support. .Sp Do you want to turn this message off? .IP "keep_source_where" 2 .IX Item "keep_source_where" Unless you are accessing the \s-1CPAN\s0 on your filesystem via a file: \s-1URL, CPAN\s0.pm needs to keep the source files it downloads somewhere. Please supply a directory where the downloaded files are to be kept. .Sp Download target directory? .IP "load_module_verbosity" 2 .IX Item "load_module_verbosity" When \s-1CPAN\s0.pm loads a module it needs for some optional feature, it usually reports about module name and version. Choose 'v' to get this message, 'none' to suppress it. .Sp Verbosity level for loading modules (none or v)? .IP "makepl_arg" 2 .IX Item "makepl_arg" Every Makefile.PL is run by perl in a separate process. Likewise we run 'make' and 'make install' in separate processes. If you have any parameters (e.g. \s-1PREFIX, UNINST\s0 or the like) you want to pass to the calls, please specify them here. .Sp If you don't understand this question, just press \s-1ENTER.\s0 .Sp Typical frequently used settings: .Sp .Vb 1 \& PREFIX=~/perl # non\-root users (please see manual for more hints) .Ve .Sp Parameters for the 'perl Makefile.PL' command? .IP "make_arg" 2 .IX Item "make_arg" Parameters for the 'make' command? Typical frequently used setting: .Sp .Vb 1 \& \-j3 # dual processor system (on GNU make) .Ve .Sp Your choice: .IP "make_install_arg" 2 .IX Item "make_install_arg" Parameters for the 'make install' command? Typical frequently used setting: .Sp .Vb 2 \& UNINST=1 # to always uninstall potentially conflicting files \& # (but do NOT use with local::lib or INSTALL_BASE) .Ve .Sp Your choice: .IP "make_install_make_command" 2 .IX Item "make_install_make_command" Do you want to use a different make command for 'make install'? Cautious people will probably prefer: .Sp .Vb 5 \& su root \-c make \& or \& sudo make \& or \& /path1/to/sudo \-u admin_account /path2/to/make .Ve .Sp or some such. Your choice: .IP "mbuildpl_arg" 2 .IX Item "mbuildpl_arg" A Build.PL is run by perl in a separate process. Likewise we run \&'./Build' and './Build install' in separate processes. If you have any parameters you want to pass to the calls, please specify them here. .Sp Typical frequently used settings: .Sp .Vb 1 \& \-\-install_base /home/xxx # different installation directory .Ve .Sp Parameters for the 'perl Build.PL' command? .IP "mbuild_arg" 2 .IX Item "mbuild_arg" Parameters for the './Build' command? Setting might be: .Sp .Vb 1 \& \-\-extra_linker_flags \-L/usr/foo/lib # non\-standard library location .Ve .Sp Your choice: .IP "mbuild_install_arg" 2 .IX Item "mbuild_install_arg" Parameters for the './Build install' command? Typical frequently used setting: .Sp .Vb 2 \& \-\-uninst 1 # uninstall conflicting files \& # (but do NOT use with local::lib or INSTALL_BASE) .Ve .Sp Your choice: .IP "mbuild_install_build_command" 2 .IX Item "mbuild_install_build_command" Do you want to use a different command for './Build install'? Sudo users will probably prefer: .Sp .Vb 5 \& su root \-c ./Build \& or \& sudo ./Build \& or \& /path1/to/sudo \-u admin_account ./Build .Ve .Sp or some such. Your choice: .IP "pager" 2 .IX Item "pager" What is your favorite pager program? .IP "prefer_installer" 2 .IX Item "prefer_installer" When you have Module::Build installed and a module comes with both a Makefile.PL and a Build.PL, which shall have precedence? .Sp The main two standard installer modules are the old and well established ExtUtils::MakeMaker (for short: \s-1EUMM\s0) which uses the Makefile.PL. And the next generation installer Module::Build (\s-1MB\s0) which works with the Build.PL (and often comes with a Makefile.PL too). If a module comes only with one of the two we will use that one but if both are supplied then a decision must be made between \s-1EUMM\s0 and \&\s-1MB.\s0 See also http://rt.cpan.org/Ticket/Display.html?id=29235 for a discussion about the right default. .Sp Or, as a third option you can choose \s-1RAND\s0 which will make a random decision (something regular \s-1CPAN\s0 testers will enjoy). .Sp In case you can choose between running a Makefile.PL or a Build.PL, which installer would you prefer (\s-1EUMM\s0 or \s-1MB\s0 or \s-1RAND\s0)? .IP "prefs_dir" 2 .IX Item "prefs_dir" \&\s-1CPAN\s0.pm can store customized build environments based on regular expressions for distribution names. These are \s-1YAML\s0 files where the default options for \s-1CPAN\s0.pm and the environment can be overridden and dialog sequences can be stored that can later be executed by an Expect.pm object. The \s-1CPAN\s0.pm distribution comes with some prefab \s-1YAML\s0 files that cover sample distributions that can be used as blueprints to store your own prefs. Please check out the distroprefs/ directory of the \s-1CPAN\s0.pm distribution to get a quick start into the prefs system. .Sp Directory where to store default options/environment/dialogs for building modules that need some customization? .IP "prerequisites_policy" 2 .IX Item "prerequisites_policy" The \s-1CPAN\s0 module can detect when a module which you are trying to build depends on prerequisites. If this happens, it can build the prerequisites for you automatically ('follow'), ask you for confirmation ('ask'), or just ignore them ('ignore'). Choosing \&'follow' also sets \s-1PERL_AUTOINSTALL\s0 and \s-1PERL_EXTUTILS_AUTOINSTALL\s0 for \&\*(L"\-\-defaultdeps\*(R" if not already set. .Sp Please set your policy to one of the three values. .Sp Policy on building prerequisites (follow, ask or ignore)? .IP "pushy_https" 2 .IX Item "pushy_https" Boolean. Defaults to true. If this option is true, the cpan shell will use https://cpan.org/ to download stuff from the \s-1CPAN.\s0 It will fall back to http://cpan.org/ if it can't handle https for some reason (missing modules, missing programs). Whenever it falls back to the http protocol, it will issue a warning. .Sp If this option is true, the option \f(CW\*(C`urllist\*(C'\fR will be ignored. Consequently, if you want to work with local mirrors via your own configured list of URLs, you will have to choose no below. .Sp Do you want to turn the pushy_https behaviour on? .IP "randomize_urllist" 2 .IX Item "randomize_urllist" \&\s-1CPAN\s0.pm can introduce some randomness when using hosts for download that are configured in the urllist parameter. Enter a numeric value between 0 and 1 to indicate how often you want to let \s-1CPAN\s0.pm try a random host from the urllist. A value of one specifies to always use a random host as the first try. A value of zero means no randomness at all. Anything in between specifies how often, on average, a random host should be tried first. .Sp Randomize parameter .IP "recommends_policy" 2 .IX Item "recommends_policy" (Experimental feature!) Some \s-1CPAN\s0 modules recommend additional, optional dependencies. These should generally be installed except in resource constrained environments. When this policy is true, recommended modules will be included with required modules. .Sp Include recommended modules? .IP "scan_cache" 2 .IX Item "scan_cache" By default, each time the \s-1CPAN\s0 module is started, cache scanning is performed to keep the cache size in sync ('atstart'). Alternatively, scanning and cleanup can happen when \s-1CPAN\s0 exits ('atexit'). To prevent any cache cleanup, answer 'never'. .Sp Perform cache scanning ('atstart', 'atexit' or 'never')? .IP "shell" 2 .IX Item "shell" What is your favorite shell? .IP "show_unparsable_versions" 2 .IX Item "show_unparsable_versions" During the 'r' command \s-1CPAN\s0.pm finds modules without version number. When the command finishes, it prints a report about this. If you want this report to be very verbose, say yes to the following variable. .Sp Show all individual modules that have no \f(CW$VERSION\fR? .IP "show_upload_date" 2 .IX Item "show_upload_date" The 'd' and the 'm' command normally only show you information they have in their in-memory database and thus will never connect to the internet. If you set the 'show_upload_date' variable to true, 'm' and \&'d' will additionally show you the upload date of the module or distribution. Per default this feature is off because it may require a net connection to get at the upload date. .Sp Always try to show upload date with 'd' and 'm' command (yes/no)? .IP "show_zero_versions" 2 .IX Item "show_zero_versions" During the 'r' command \s-1CPAN\s0.pm finds modules with a version number of zero. When the command finishes, it prints a report about this. If you want this report to be very verbose, say yes to the following variable. .Sp Show all individual modules that have a \f(CW$VERSION\fR of zero? .IP "suggests_policy" 2 .IX Item "suggests_policy" (Experimental feature!) Some \s-1CPAN\s0 modules suggest additional, optional dependencies. These 'suggest' dependencies provide enhanced operation. When this policy is true, suggested modules will be included with required modules. .Sp Include suggested modules? .IP "tar_verbosity" 2 .IX Item "tar_verbosity" When \s-1CPAN\s0.pm uses the tar command, which switch for the verbosity shall be used? Choose 'none' for quiet operation, 'v' for file name listing, 'vv' for full listing. .Sp Tar command verbosity level (none or v or vv)? .IP "term_is_latin" 2 .IX Item "term_is_latin" The next option deals with the charset (a.k.a. character set) your terminal supports. In general, \s-1CPAN\s0 is English speaking territory, so the charset does not matter much but some \s-1CPAN\s0 have names that are outside the \s-1ASCII\s0 range. If your terminal supports \s-1UTF\-8,\s0 you should say no to the next question. If it expects \s-1ISO\-8859\-1\s0 (also known as \&\s-1LATIN1\s0) then you should say yes. If it supports neither, your answer does not matter because you will not be able to read the names of some authors anyway. If you answer no, names will be output in \s-1UTF\-8.\s0 .Sp Your terminal expects \s-1ISO\-8859\-1\s0 (yes/no)? .IP "term_ornaments" 2 .IX Item "term_ornaments" When using Term::ReadLine, you can turn ornaments on so that your input stands out against the output from \s-1CPAN\s0.pm. .Sp Do you want to turn ornaments on? .IP "test_report" 2 .IX Item "test_report" The goal of the \s-1CPAN\s0 Testers project (http://testers.cpan.org/) is to test as many \s-1CPAN\s0 packages as possible on as many platforms as possible. This provides valuable feedback to module authors and potential users to identify bugs or platform compatibility issues and improves the overall quality and value of \s-1CPAN.\s0 .Sp One way you can contribute is to send test results for each module that you install. If you install the CPAN::Reporter module, you have the option to automatically generate and deliver test reports to \s-1CPAN\s0 Testers whenever you run tests on a \s-1CPAN\s0 package. .Sp See the CPAN::Reporter documentation for additional details and configuration settings. If your firewall blocks outgoing traffic, you may need to configure CPAN::Reporter before sending reports. .Sp Generate test reports if CPAN::Reporter is installed (yes/no)? .IP "perl5lib_verbosity" 2 .IX Item "perl5lib_verbosity" When \s-1CPAN\s0.pm extends \f(CW@INC\fR via \s-1PERL5LIB,\s0 it prints a list of directories added (or a summary of how many directories are added). Choose 'v' to get this message, 'none' to suppress it. .Sp Verbosity level for \s-1PERL5LIB\s0 changes (none or v)? .IP "prefer_external_tar" 2 .IX Item "prefer_external_tar" Per default all untar operations are done with the perl module Archive::Tar; by setting this variable to true the external tar command is used if available; on Unix this is usually preferred because they have a reliable and fast gnutar implementation. .Sp Use the external tar program instead of Archive::Tar? .IP "trust_test_report_history" 2 .IX Item "trust_test_report_history" When a distribution has already been tested by CPAN::Reporter on this machine, \s-1CPAN\s0 can skip the test phase and just rely on the test report history instead. .Sp Note that this will not apply to distributions that failed tests because of missing dependencies. Also, tests can be run regardless of the history using \*(L"force\*(R". .Sp Do you want to rely on the test report history (yes/no)? .IP "urllist_ping_external" 2 .IX Item "urllist_ping_external" When automatic selection of the nearest cpan mirrors is performed, turn on the use of the external ping via Net::Ping::External. This is recommended in the case the local network has a transparent proxy. .Sp Do you want to use the external ping command when autoselecting mirrors? .IP "urllist_ping_verbose" 2 .IX Item "urllist_ping_verbose" When automatic selection of the nearest cpan mirrors is performed, this option can be used to turn on verbosity during the selection process. .Sp Do you want to see verbosity turned on when autoselecting mirrors? .IP "use_prompt_default" 2 .IX Item "use_prompt_default" When this is true, \s-1CPAN\s0 will set \s-1PERL_MM_USE_DEFAULT\s0 to a true value. This causes ExtUtils::MakeMaker (and compatible) prompts to use default values instead of stopping to prompt you to answer questions. It also sets \s-1NONINTERACTIVE_TESTING\s0 to a true value to signal more generally that distributions should not try to interact with you. .Sp Do you want to use prompt defaults (yes/no)? .IP "use_sqlite" 2 .IX Item "use_sqlite" CPAN::SQLite is a layer between the index files that are downloaded from the \s-1CPAN\s0 and \s-1CPAN\s0.pm that speeds up metadata queries and reduces memory consumption of \s-1CPAN\s0.pm considerably. .Sp Use CPAN::SQLite if available? (yes/no)? .IP "version_timeout" 2 .IX Item "version_timeout" This timeout prevents \s-1CPAN\s0 from hanging when trying to parse a pathologically coded \f(CW$VERSION\fR from a module. .Sp The default is 15 seconds. If you set this value to 0, no timeout will occur, but this is not recommended. .Sp Timeout for parsing module versions? .IP "yaml_load_code" 2 .IX Item "yaml_load_code" Both \s-1YAML\s0.pm and YAML::Syck are capable of deserialising code. As this requires a string eval, which might be a security risk, you can use this option to enable or disable the deserialisation of code via CPAN::DeferredCode. (Note: This does not work under perl 5.6) .Sp Do you want to enable code deserialisation (yes/no)? .IP "yaml_module" 2 .IX Item "yaml_module" At the time of this writing (2009\-03) there are three \s-1YAML\s0 implementations working: \s-1YAML,\s0 YAML::Syck, and \s-1YAML::XS.\s0 The latter two are faster but need a C compiler installed on your system. There may be more alternative \s-1YAML\s0 conforming modules. When I tried two other players, YAML::Tiny and YAML::Perl, they seemed not powerful enough to work with \s-1CPAN\s0.pm. This may have changed in the meantime. .Sp Which \s-1YAML\s0 implementation would you prefer? .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK@O\u{ Types::Serialiser::Error.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Serialiser::Error 3" .TH Serialiser::Error 3 "2013-10-27" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Types::Serialiser::Error \- dummy module for Types::Serialiser .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& # do not "use" yourself .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module exists only to provide overload resolution for Storable and similar modules that assume that class name equals module name. See Types::Serialiser for more info about this class. .SH "AUTHOR" .IX Header "AUTHOR" .Vb 2 \& Marc Lehmann \& http://home.schmorp.de/ .Ve PK@O\*'E""CPAN::Mirrors.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::Mirrors 3" .TH CPAN::Mirrors 3 "2020-05-23" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::Mirrors \- Get CPAN mirror information and select a fast one .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use CPAN::Mirrors; \& \& my $mirrors = CPAN::Mirrors\->new( $mirrored_by_file ); \& \& my $seen = {}; \& \& my $best_continent = $mirrors\->find_best_continents( { seen => $seen } ); \& my @mirrors = $mirrors\->get_mirrors_by_continents( $best_continent ); \& \& my $callback = sub { \& my( $m ) = @_; \& printf "%s = %s\en", $m\->hostname, $m\->rtt \& }; \& $mirrors\->get_mirrors_timings( \e@mirrors, $seen, $callback, %args ); \& \& @mirrors = sort { $a\->rtt <=> $b\->rtt } @mirrors; \& \& print "Best mirrors are ", map( { $_\->rtt } @mirrors[0..3] ), "\en"; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" .IP "new( \s-1LOCAL_FILE_NAME\s0 )" 4 .IX Item "new( LOCAL_FILE_NAME )" Create a new CPAN::Mirrors object from \s-1LOCAL_FILE_NAME.\s0 This file should look like that in http://www.cpan.org/MIRRORED.BY . .IP "\fBcontinents()\fR" 4 .IX Item "continents()" Return a list of continents based on those defined in \fI\s-1MIRRORED.BY\s0\fR. .IP "countries( [\s-1CONTINENTS\s0] )" 4 .IX Item "countries( [CONTINENTS] )" Return a list of countries based on those defined in \fI\s-1MIRRORED.BY\s0\fR. It only returns countries for the continents you specify (as defined in \f(CW\*(C`continents\*(C'\fR). If you don't specify any continents, it returns all of the countries listed in \fI\s-1MIRRORED.BY\s0\fR. .IP "mirrors( [\s-1COUNTRIES\s0] )" 4 .IX Item "mirrors( [COUNTRIES] )" Return a list of mirrors based on those defined in \fI\s-1MIRRORED.BY\s0\fR. It only returns mirrors for the countries you specify (as defined in \f(CW\*(C`countries\*(C'\fR). If you don't specify any countries, it returns all of the mirrors listed in \fI\s-1MIRRORED.BY\s0\fR. .IP "get_mirrors_by_countries( [\s-1COUNTRIES\s0] )" 4 .IX Item "get_mirrors_by_countries( [COUNTRIES] )" A more sensible synonym for mirrors. .IP "get_mirrors_by_continents( [\s-1CONTINENTS\s0] )" 4 .IX Item "get_mirrors_by_continents( [CONTINENTS] )" Return a list of mirrors for all of continents you specify. If you don't specify any continents, it returns all of the mirrors. .Sp You can specify a single continent or an array reference of continents. .IP "get_countries_by_continents( [\s-1CONTINENTS\s0] )" 4 .IX Item "get_countries_by_continents( [CONTINENTS] )" A more sensible synonym for countries. .IP "default_mirror" 4 .IX Item "default_mirror" Returns the default mirror, http://www.cpan.org/ . This mirror uses dynamic \s-1DNS\s0 to give a close mirror. .IP "best_mirrors" 4 .IX Item "best_mirrors" \&\f(CW\*(C`best_mirrors\*(C'\fR checks for the best mirrors based on the list of continents you pass, or, without that, all continents, as defined by \f(CW\*(C`CPAN::Mirrored::By\*(C'\fR. It pings each mirror, up to the value of \&\f(CW\*(C`how_many\*(C'\fR. In list context, it returns up to \f(CW\*(C`how_many\*(C'\fR mirrors. In scalar context, it returns the single best mirror. .Sp Arguments .Sp .Vb 5 \& how_many \- the number of mirrors to return. Default: 1 \& callback \- a callback for find_best_continents \& verbose \- true or false on all the whining and moaning. Default: false \& continents \- an array ref of the continents to check \& external_ping \- if true, use external ping via Net::Ping::External. Default: false .Ve .Sp If you don't specify the continents, \f(CW\*(C`best_mirrors\*(C'\fR calls \&\f(CW\*(C`find_best_continents\*(C'\fR to get the list of continents to check. .Sp If you don't have Net::Ping v2.13 or later, needed for timings, this returns the default mirror. .Sp \&\f(CW\*(C`external_ping\*(C'\fR should be set and then \f(CW\*(C`Net::Ping::External\*(C'\fR needs to be installed, if the local network has a transparent proxy. .IP "get_n_random_mirrors_by_continents( N, [\s-1CONTINENTS\s0] )" 4 .IX Item "get_n_random_mirrors_by_continents( N, [CONTINENTS] )" Returns up to N random mirrors for the specified continents. Specify the continents as an array reference. .ie n .IP "get_mirrors_timings( \s-1MIRROR_LIST, SEEN, CALLBACK,\s0 %ARGS );" 4 .el .IP "get_mirrors_timings( \s-1MIRROR_LIST, SEEN, CALLBACK,\s0 \f(CW%ARGS\fR );" 4 .IX Item "get_mirrors_timings( MIRROR_LIST, SEEN, CALLBACK, %ARGS );" Pings the listed mirrors and returns a list of mirrors sorted in ascending ping times. .Sp \&\f(CW\*(C`MIRROR_LIST\*(C'\fR is an anonymous array of \f(CW\*(C`CPAN::Mirrored::By\*(C'\fR objects to ping. .Sp The optional argument \f(CW\*(C`SEEN\*(C'\fR is a hash reference used to track the mirrors you've already pinged. .Sp The optional argument \f(CW\*(C`CALLBACK\*(C'\fR is a subroutine reference to call after each ping. It gets the \f(CW\*(C`CPAN::Mirrored::By\*(C'\fR object after each ping. .IP "find_best_continents( \s-1HASH_REF\s0 );" 4 .IX Item "find_best_continents( HASH_REF );" \&\f(CW\*(C`find_best_continents\*(C'\fR goes through each continent and pings \f(CW\*(C`N\*(C'\fR random mirrors on that continent. It then orders the continents by ascending median ping time. In list context, it returns the ordered list of continent. In scalar context, it returns the same list as an anonymous array. .Sp Arguments: .Sp .Vb 6 \& n \- the number of hosts to ping for each continent. Default: 3 \& seen \- a hashref of cached hostname ping times \& verbose \- true or false for noisy or quiet. Default: false \& callback \- a subroutine to run after each ping. \& ping_cache_limit \- how long, in seconds, to reuse previous ping times. \& Default: 1 day .Ve .Sp The \f(CW\*(C`seen\*(C'\fR hash has hostnames as keys and anonymous arrays as values. The anonymous array is a triplet of a \f(CW\*(C`CPAN::Mirrored::By\*(C'\fR object, a ping time, and the epoch time for the measurement. .Sp The callback subroutine gets the \f(CW\*(C`CPAN::Mirrored::By\*(C'\fR object, the ping time, and measurement time (the same things in the \f(CW\*(C`seen\*(C'\fR hashref) as arguments. \f(CW\*(C`find_best_continents\*(C'\fR doesn't care what the callback does and ignores the return value. .Sp With a low value for \f(CW\*(C`N\*(C'\fR, a single mirror might skew the results enough to choose a worse continent. If you have that problem, try a larger value. .SH "AUTHOR" .IX Header "AUTHOR" Andreas Koenig \f(CW\*(C`\*(C'\fR, David Golden \f(CW\*(C`\*(C'\fR, brian d foy \f(CW\*(C`\*(C'\fR .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP See PK@O\lg CPAN::Kwalify.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::Kwalify 3" .TH CPAN::Kwalify 3 "2012-09-08" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::Kwalify \- Interface between CPAN.pm and Kwalify.pm .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use CPAN::Kwalify; \& validate($schema_name, $data, $file, $doc); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" .ie n .IP "_validate($schema_name, $data, $file, $doc)" 4 .el .IP "_validate($schema_name, \f(CW$data\fR, \f(CW$file\fR, \f(CW$doc\fR)" 4 .IX Item "_validate($schema_name, $data, $file, $doc)" \&\f(CW$schema_name\fR is the name of a supported schema. Currently only \&\f(CW\*(C`distroprefs\*(C'\fR is supported. \f(CW$data\fR is the data to be validated. \f(CW$file\fR is the absolute path to the file the data are coming from. \f(CW$doc\fR is the index of the document within \f(CW$doc\fR that is to be validated. The last two arguments are only there for better error reporting. .Sp Relies on being called from within \s-1CPAN\s0.pm. .Sp Dies if something fails. Does not return anything useful. .IP "yaml($schema_name)" 4 .IX Item "yaml($schema_name)" Returns the \s-1YAML\s0 text of that schema. Dies if something fails. .SH "AUTHOR" .IX Header "AUTHOR" Andreas Koenig \f(CW\*(C`\*(C'\fR .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP See PK@O\އg! ! CPAN::Nox.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::Nox 3" .TH CPAN::Nox 3 "2016-08-17" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::Nox \- Wrapper around CPAN.pm without using any XS module .SH "SYNOPSIS" .IX Header "SYNOPSIS" Interactive mode: .PP .Vb 1 \& perl \-MCPAN::Nox \-e shell; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This package has the same functionality as \s-1CPAN\s0.pm, but tries to prevent the usage of compiled extensions during its own execution. Its primary purpose is a rescue in case you upgraded perl and broke binary compatibility somehow. .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1CPAN\s0 PK@O\[//CPAN.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN 3" .TH CPAN 3 "2023-05-10" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN \- query, download and build perl modules from CPAN sites .SH "SYNOPSIS" .IX Header "SYNOPSIS" Interactive mode: .PP .Vb 1 \& perl \-MCPAN \-e shell .Ve .PP \&\-\-or\*(-- .PP .Vb 1 \& cpan .Ve .PP Basic commands: .PP .Vb 1 \& # Modules: \& \& cpan> install Acme::Meta # in the shell \& \& CPAN::Shell\->install("Acme::Meta"); # in perl \& \& # Distributions: \& \& cpan> install NWCLARK/Acme\-Meta\-0.02.tar.gz # in the shell \& \& CPAN::Shell\-> \& install("NWCLARK/Acme\-Meta\-0.02.tar.gz"); # in perl \& \& # module objects: \& \& $mo = CPAN::Shell\->expandany($mod); \& $mo = CPAN::Shell\->expand("Module",$mod); # same thing \& \& # distribution objects: \& \& $do = CPAN::Shell\->expand("Module",$mod)\->distribution; \& $do = CPAN::Shell\->expandany($distro); # same thing \& $do = CPAN::Shell\->expand("Distribution", \& $distro); # same thing .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The \s-1CPAN\s0 module automates or at least simplifies the make and install of perl modules and extensions. It includes some primitive searching capabilities and knows how to use \s-1LWP,\s0 HTTP::Tiny, Net::FTP and certain external download clients to fetch distributions from the net. .PP These are fetched from one or more mirrored \s-1CPAN\s0 (Comprehensive Perl Archive Network) sites and unpacked in a dedicated directory. .PP The \s-1CPAN\s0 module also supports named and versioned \&\fIbundles\fR of modules. Bundles simplify handling of sets of related modules. See Bundles below. .PP The package contains a session manager and a cache manager. The session manager keeps track of what has been fetched, built, and installed in the current session. The cache manager keeps track of the disk space occupied by the make processes and deletes excess space using a simple \s-1FIFO\s0 mechanism. .PP All methods provided are accessible in a programmer style and in an interactive shell style. .ie n .SS "CPAN::shell([$prompt, $command]) Starting Interactive Mode" .el .SS "CPAN::shell([$prompt, \f(CW$command\fP]) Starting Interactive Mode" .IX Subsection "CPAN::shell([$prompt, $command]) Starting Interactive Mode" Enter interactive mode by running .PP .Vb 1 \& perl \-MCPAN \-e shell .Ve .PP or .PP .Vb 1 \& cpan .Ve .PP which puts you into a readline interface. If \f(CW\*(C`Term::ReadKey\*(C'\fR and either of \f(CW\*(C`Term::ReadLine::Perl\*(C'\fR or \f(CW\*(C`Term::ReadLine::Gnu\*(C'\fR are installed, history and command completion are supported. .PP Once at the command line, type \f(CW\*(C`h\*(C'\fR for one-page help screen; the rest should be self-explanatory. .PP The function call \f(CW\*(C`shell\*(C'\fR takes two optional arguments: one the prompt, the second the default initial command line (the latter only works if a real ReadLine interface module is installed). .PP The most common uses of the interactive modes are .IP "Searching for authors, bundles, distribution files and modules" 2 .IX Item "Searching for authors, bundles, distribution files and modules" There are corresponding one-letter commands \f(CW\*(C`a\*(C'\fR, \f(CW\*(C`b\*(C'\fR, \f(CW\*(C`d\*(C'\fR, and \f(CW\*(C`m\*(C'\fR for each of the four categories and another, \f(CW\*(C`i\*(C'\fR for any of the mentioned four. Each of the four entities is implemented as a class with slightly differing methods for displaying an object. .Sp Arguments to these commands are either strings exactly matching the identification string of an object, or regular expressions matched case-insensitively against various attributes of the objects. The parser only recognizes a regular expression when you enclose it with slashes. .Sp The principle is that the number of objects found influences how an item is displayed. If the search finds one item, the result is displayed with the rather verbose method \f(CW\*(C`as_string\*(C'\fR, but if more than one is found, each object is displayed with the terse method \&\f(CW\*(C`as_glimpse\*(C'\fR. .Sp Examples: .Sp .Vb 10 \& cpan> m Acme::MetaSyntactic \& Module id = Acme::MetaSyntactic \& CPAN_USERID BOOK (Philippe Bruhat (BooK) <[...]>) \& CPAN_VERSION 0.99 \& CPAN_FILE B/BO/BOOK/Acme\-MetaSyntactic\-0.99.tar.gz \& UPLOAD_DATE 2006\-11\-06 \& MANPAGE Acme::MetaSyntactic \- Themed metasyntactic variables names \& INST_FILE /usr/local/lib/perl/5.10.0/Acme/MetaSyntactic.pm \& INST_VERSION 0.99 \& cpan> a BOOK \& Author id = BOOK \& EMAIL [...] \& FULLNAME Philippe Bruhat (BooK) \& cpan> d BOOK/Acme\-MetaSyntactic\-0.99.tar.gz \& Distribution id = B/BO/BOOK/Acme\-MetaSyntactic\-0.99.tar.gz \& CPAN_USERID BOOK (Philippe Bruhat (BooK) <[...]>) \& CONTAINSMODS Acme::MetaSyntactic Acme::MetaSyntactic::Alias [...] \& UPLOAD_DATE 2006\-11\-06 \& cpan> m /lorem/ \& Module = Acme::MetaSyntactic::loremipsum (BOOK/Acme\-MetaSyntactic\-0.99.tar.gz) \& Module Text::Lorem (ADEOLA/Text\-Lorem\-0.3.tar.gz) \& Module Text::Lorem::More (RKRIMEN/Text\-Lorem\-More\-0.12.tar.gz) \& Module Text::Lorem::More::Source (RKRIMEN/Text\-Lorem\-More\-0.12.tar.gz) \& cpan> i /berlin/ \& Distribution BEATNIK/Filter\-NumberLines\-0.02.tar.gz \& Module = DateTime::TimeZone::Europe::Berlin (DROLSKY/DateTime\-TimeZone\-0.7904.tar.gz) \& Module Filter::NumberLines (BEATNIK/Filter\-NumberLines\-0.02.tar.gz) \& Author [...] .Ve .Sp The examples illustrate several aspects: the first three queries target modules, authors, or distros directly and yield exactly one result. The last two use regular expressions and yield several results. The last one targets all of bundles, modules, authors, and distros simultaneously. When more than one result is available, they are printed in one-line format. .ie n .IP """get"", ""make"", ""test"", ""install"", ""clean"" modules or distributions" 2 .el .IP "\f(CWget\fR, \f(CWmake\fR, \f(CWtest\fR, \f(CWinstall\fR, \f(CWclean\fR modules or distributions" 2 .IX Item "get, make, test, install, clean modules or distributions" These commands take any number of arguments and investigate what is necessary to perform the action. Argument processing is as follows: .Sp .Vb 5 \& known module name in format Foo/Bar.pm module \& other embedded slash distribution \& \- with trailing slash dot directory \& enclosing slashes regexp \& known module name in format Foo::Bar module .Ve .Sp If the argument is a distribution file name (recognized by embedded slashes), it is processed. If it is a module, \s-1CPAN\s0 determines the distribution file in which this module is included and processes that, following any dependencies named in the module's \s-1META\s0.yml or Makefile.PL (this behavior is controlled by the configuration parameter \f(CW\*(C`prerequisites_policy\*(C'\fR). If an argument is enclosed in slashes it is treated as a regular expression: it is expanded and if the result is a single object (distribution, bundle or module), this object is processed. .Sp Example: .Sp .Vb 3 \& install Dummy::Perl # installs the module \& install AUXXX/Dummy\-Perl\-3.14.tar.gz # installs that distribution \& install /Dummy\-Perl\-3.14/ # same if the regexp is unambiguous .Ve .Sp \&\f(CW\*(C`get\*(C'\fR downloads a distribution file and untars or unzips it, \f(CW\*(C`make\*(C'\fR builds it, \f(CW\*(C`test\*(C'\fR runs the test suite, and \f(CW\*(C`install\*(C'\fR installs it. .Sp Any \f(CW\*(C`make\*(C'\fR or \f(CW\*(C`test\*(C'\fR is run unconditionally. An .Sp .Vb 1 \& install .Ve .Sp is also run unconditionally. But for .Sp .Vb 1 \& install .Ve .Sp \&\s-1CPAN\s0 checks whether an install is needed and prints \&\fImodule up to date\fR if the distribution file containing the module doesn't need updating. .Sp \&\s-1CPAN\s0 also keeps track of what it has done within the current session and doesn't try to build a package a second time regardless of whether it succeeded or not. It does not repeat a test run if the test has been run successfully before. Same for install runs. .Sp The \f(CW\*(C`force\*(C'\fR pragma may precede another command (currently: \f(CW\*(C`get\*(C'\fR, \&\f(CW\*(C`make\*(C'\fR, \f(CW\*(C`test\*(C'\fR, or \f(CW\*(C`install\*(C'\fR) to execute the command from scratch and attempt to continue past certain errors. See the section below on the \f(CW\*(C`force\*(C'\fR and the \f(CW\*(C`fforce\*(C'\fR pragma. .Sp The \f(CW\*(C`notest\*(C'\fR pragma skips the test part in the build process. .Sp Example: .Sp .Vb 1 \& cpan> notest install Tk .Ve .Sp A \f(CW\*(C`clean\*(C'\fR command results in a .Sp .Vb 1 \& make clean .Ve .Sp being executed within the distribution file's working directory. .ie n .IP """readme"", ""perldoc"", ""look"" module or distribution" 2 .el .IP "\f(CWreadme\fR, \f(CWperldoc\fR, \f(CWlook\fR module or distribution" 2 .IX Item "readme, perldoc, look module or distribution" \&\f(CW\*(C`readme\*(C'\fR displays the \s-1README\s0 file of the associated distribution. \&\f(CW\*(C`Look\*(C'\fR gets and untars (if not yet done) the distribution file, changes to the appropriate directory and opens a subshell process in that directory. \f(CW\*(C`perldoc\*(C'\fR displays the module's pod documentation in html or plain text format. .ie n .IP """ls"" author" 2 .el .IP "\f(CWls\fR author" 2 .IX Item "ls author" .PD 0 .ie n .IP """ls"" globbing_expression" 2 .el .IP "\f(CWls\fR globbing_expression" 2 .IX Item "ls globbing_expression" .PD The first form lists all distribution files in and below an author's \&\s-1CPAN\s0 directory as stored in the \s-1CHECKSUMS\s0 files distributed on \&\s-1CPAN.\s0 The listing recurses into subdirectories. .Sp The second form limits or expands the output with shell globbing as in the following examples: .Sp .Vb 3 \& ls JV/make* \& ls GSAR/*make* \& ls */*make* .Ve .Sp The last example is very slow and outputs extra progress indicators that break the alignment of the result. .Sp Note that globbing only lists directories explicitly asked for, for example FOO/* will not list FOO/bar/Acme\-Sthg\-n.nn.tar.gz. This may be regarded as a bug that may be changed in some future version. .ie n .IP """failed""" 2 .el .IP "\f(CWfailed\fR" 2 .IX Item "failed" The \f(CW\*(C`failed\*(C'\fR command reports all distributions that failed on one of \&\f(CW\*(C`make\*(C'\fR, \f(CW\*(C`test\*(C'\fR or \f(CW\*(C`install\*(C'\fR for some reason in the currently running shell session. .IP "Persistence between sessions" 2 .IX Item "Persistence between sessions" If the \f(CW\*(C`YAML\*(C'\fR or the \f(CW\*(C`YAML::Syck\*(C'\fR module is installed a record of the internal state of all modules is written to disk after each step. The files contain a signature of the currently running perl version for later perusal. .Sp If the configurations variable \f(CW\*(C`build_dir_reuse\*(C'\fR is set to a true value, then \s-1CPAN\s0.pm reads the collected \s-1YAML\s0 files. If the stored signature matches the currently running perl, the stored state is loaded into memory such that persistence between sessions is effectively established. .ie n .IP "The ""force"" and the ""fforce"" pragma" 2 .el .IP "The \f(CWforce\fR and the \f(CWfforce\fR pragma" 2 .IX Item "The force and the fforce pragma" To speed things up in complex installation scenarios, \s-1CPAN\s0.pm keeps track of what it has already done and refuses to do some things a second time. A \f(CW\*(C`get\*(C'\fR, a \f(CW\*(C`make\*(C'\fR, and an \f(CW\*(C`install\*(C'\fR are not repeated. A \f(CW\*(C`test\*(C'\fR is repeated only if the previous test was unsuccessful. The diagnostic message when \s-1CPAN\s0.pm refuses to do something a second time is one of \fIHas already been \fR\f(CW\*(C`unwrapped|made|tested successfully\*(C'\fR or something similar. Another situation where \s-1CPAN\s0 refuses to act is an \&\f(CW\*(C`install\*(C'\fR if the corresponding \f(CW\*(C`test\*(C'\fR was not successful. .Sp In all these cases, the user can override this stubborn behaviour by prepending the command with the word force, for example: .Sp .Vb 4 \& cpan> force get Foo \& cpan> force make AUTHOR/Bar\-3.14.tar.gz \& cpan> force test Baz \& cpan> force install Acme::Meta .Ve .Sp Each \fIforced\fR command is executed with the corresponding part of its memory erased. .Sp The \f(CW\*(C`fforce\*(C'\fR pragma is a variant that emulates a \f(CW\*(C`force get\*(C'\fR which erases the entire memory followed by the action specified, effectively restarting the whole get/make/test/install procedure from scratch. .IP "Lockfile" 2 .IX Item "Lockfile" Interactive sessions maintain a lockfile, by default \f(CW\*(C`~/.cpan/.lock\*(C'\fR. Batch jobs can run without a lockfile and not disturb each other. .Sp The shell offers to run in \fIdowngraded mode\fR when another process is holding the lockfile. This is an experimental feature that is not yet tested very well. This second shell then does not write the history file, does not use the metadata file, and has a different prompt. .IP "Signals" 2 .IX Item "Signals" \&\s-1CPAN\s0.pm installs signal handlers for \s-1SIGINT\s0 and \s-1SIGTERM.\s0 While you are in the cpan-shell, it is intended that you can press \f(CW\*(C`^C\*(C'\fR anytime and return to the cpan-shell prompt. A \s-1SIGTERM\s0 will cause the cpan-shell to clean up and leave the shell loop. You can emulate the effect of a \&\s-1SIGTERM\s0 by sending two consecutive SIGINTs, which usually means by pressing \f(CW\*(C`^C\*(C'\fR twice. .Sp \&\s-1CPAN\s0.pm ignores \s-1SIGPIPE.\s0 If the user sets \f(CW\*(C`inactivity_timeout\*(C'\fR, a \&\s-1SIGALRM\s0 is used during the run of the \f(CW\*(C`perl Makefile.PL\*(C'\fR or \f(CW\*(C`perl Build.PL\*(C'\fR subprocess. A \s-1SIGALRM\s0 is also used during module version parsing, and is controlled by \f(CW\*(C`version_timeout\*(C'\fR. .SS "CPAN::Shell" .IX Subsection "CPAN::Shell" The commands available in the shell interface are methods in the package CPAN::Shell. If you enter the shell command, your input is split by the \fBText::ParseWords::shellwords()\fR routine, which acts like most shells do. The first word is interpreted as the method to be invoked, and the rest of the words are treated as the method's arguments. Continuation lines are supported by ending a line with a literal backslash. .SS "autobundle" .IX Subsection "autobundle" \&\f(CW\*(C`autobundle\*(C'\fR writes a bundle file into the \&\f(CW\*(C`$CPAN::Config\->{cpan_home}/Bundle\*(C'\fR directory. The file contains a list of all modules that are both available from \s-1CPAN\s0 and currently installed within \f(CW@INC\fR. Duplicates of each distribution are suppressed. The name of the bundle file is based on the current date and a counter, e.g. \fIBundle/Snapshot_2012_05_21_00.pm\fR. This is installed again by running \f(CW\*(C`cpan Bundle::Snapshot_2012_05_21_00\*(C'\fR, or installing \&\f(CW\*(C`Bundle::Snapshot_2012_05_21_00\*(C'\fR from the \s-1CPAN\s0 shell. .PP Return value: path to the written file. .SS "hosts" .IX Subsection "hosts" Note: this feature is still in alpha state and may change in future versions of \s-1CPAN\s0.pm .PP This commands provides a statistical overview over recent download activities. The data for this is collected in the \s-1YAML\s0 file \&\f(CW\*(C`FTPstats.yml\*(C'\fR in your \f(CW\*(C`cpan_home\*(C'\fR directory. If no \s-1YAML\s0 module is configured or \s-1YAML\s0 not installed, no stats are provided. .IP "install_tested" 4 .IX Item "install_tested" Install all distributions that have been tested successfully but have not yet been installed. See also \f(CW\*(C`is_tested\*(C'\fR. .IP "is_tested" 4 .IX Item "is_tested" List all build directories of distributions that have been tested successfully but have not yet been installed. See also \&\f(CW\*(C`install_tested\*(C'\fR. .SS "mkmyconfig" .IX Subsection "mkmyconfig" \&\fBmkmyconfig()\fR writes your own CPAN::MyConfig file into your \f(CW\*(C`~/.cpan/\*(C'\fR directory so that you can save your own preferences instead of the system-wide ones. .SS "r [Module|/Regexp/]..." .IX Subsection "r [Module|/Regexp/]..." scans current perl installation for modules that have a newer version available on \s-1CPAN\s0 and provides a list of them. If called without argument, all potential upgrades are listed; if called with arguments the list is filtered to the modules and regexps given as arguments. .PP The listing looks something like this: .PP .Vb 10 \& Package namespace installed latest in CPAN file \& CPAN 1.94_64 1.9600 ANDK/CPAN\-1.9600.tar.gz \& CPAN::Reporter 1.1801 1.1902 DAGOLDEN/CPAN\-Reporter\-1.1902.tar.gz \& YAML 0.70 0.73 INGY/YAML\-0.73.tar.gz \& YAML::Syck 1.14 1.17 AVAR/YAML\-Syck\-1.17.tar.gz \& YAML::Tiny 1.44 1.50 ADAMK/YAML\-Tiny\-1.50.tar.gz \& CGI 3.43 3.55 MARKSTOS/CGI.pm\-3.55.tar.gz \& Module::Build::YAML 1.40 1.41 DAGOLDEN/Module\-Build\-0.3800.tar.gz \& TAP::Parser::Result::YAML 3.22 3.23 ANDYA/Test\-Harness\-3.23.tar.gz \& YAML::XS 0.34 0.35 INGY/YAML\-LibYAML\-0.35.tar.gz .Ve .PP It suppresses duplicates in the column \f(CW\*(C`in CPAN file\*(C'\fR such that distributions with many upgradeable modules are listed only once. .PP Note that the list is not sorted. .SS "recent ***EXPERIMENTAL COMMAND***" .IX Subsection "recent ***EXPERIMENTAL COMMAND***" The \f(CW\*(C`recent\*(C'\fR command downloads a list of recent uploads to \s-1CPAN\s0 and displays them \fIslowly\fR. While the command is running, a \f(CW$SIG\fR{\s-1INT\s0} exits the loop after displaying the current item. .PP \&\fBNote\fR: This command requires XML::LibXML installed. .PP \&\fBNote\fR: This whole command currently is just a hack and will probably change in future versions of \s-1CPAN\s0.pm, but the general approach will likely remain. .PP \&\fBNote\fR: See also smoke .SS "recompile" .IX Subsection "recompile" \&\fBrecompile()\fR is a special command that takes no argument and runs the make/test/install cycle with brute force over all installed dynamically loadable extensions (a.k.a. \s-1XS\s0 modules) with 'force' in effect. The primary purpose of this command is to finish a network installation. Imagine you have a common source tree for two different architectures. You decide to do a completely independent fresh installation. You start on one architecture with the help of a Bundle file produced earlier. \s-1CPAN\s0 installs the whole Bundle for you, but when you try to repeat the job on the second architecture, \s-1CPAN\s0 responds with a \f(CW"Foo up to date"\fR message for all modules. So you invoke \s-1CPAN\s0's recompile on the second architecture and you're done. .PP Another popular use for \f(CW\*(C`recompile\*(C'\fR is to act as a rescue in case your perl breaks binary compatibility. If one of the modules that \s-1CPAN\s0 uses is in turn depending on binary compatibility (so you cannot run \s-1CPAN\s0 commands), then you should try the CPAN::Nox module for recovery. .SS "report Bundle|Distribution|Module" .IX Subsection "report Bundle|Distribution|Module" The \f(CW\*(C`report\*(C'\fR command temporarily turns on the \f(CW\*(C`test_report\*(C'\fR config variable, then runs the \f(CW\*(C`force test\*(C'\fR command with the given arguments. The \f(CW\*(C`force\*(C'\fR pragma reruns the tests and repeats every step that might have failed before. .SS "smoke ***EXPERIMENTAL COMMAND***" .IX Subsection "smoke ***EXPERIMENTAL COMMAND***" \&\fB*** \s-1WARNING:\s0 this command downloads and executes software from \s-1CPAN\s0 to your computer of completely unknown status. You should never do this with your normal account and better have a dedicated well separated and secured machine to do this. ***\fR .PP The \f(CW\*(C`smoke\*(C'\fR command takes the list of recent uploads to \s-1CPAN\s0 as provided by the \f(CW\*(C`recent\*(C'\fR command and tests them all. While the command is running \f(CW$SIG\fR{\s-1INT\s0} is defined to mean that the current item shall be skipped. .PP \&\fBNote\fR: This whole command currently is just a hack and will probably change in future versions of \s-1CPAN\s0.pm, but the general approach will likely remain. .PP \&\fBNote\fR: See also recent .SS "upgrade [Module|/Regexp/]..." .IX Subsection "upgrade [Module|/Regexp/]..." The \f(CW\*(C`upgrade\*(C'\fR command first runs an \f(CW\*(C`r\*(C'\fR command with the given arguments and then installs the newest versions of all modules that were listed by that. .ie n .SS "The four ""CPAN::*"" Classes: Author, Bundle, Module, Distribution" .el .SS "The four \f(CWCPAN::*\fP Classes: Author, Bundle, Module, Distribution" .IX Subsection "The four CPAN::* Classes: Author, Bundle, Module, Distribution" Although it may be considered internal, the class hierarchy does matter for both users and programmer. \s-1CPAN\s0.pm deals with the four classes mentioned above, and those classes all share a set of methods. Classical single polymorphism is in effect. A metaclass object registers all objects of all kinds and indexes them with a string. The strings referencing objects have a separated namespace (well, not completely separated): .PP .Vb 1 \& Namespace Class \& \& words containing a "/" (slash) Distribution \& words starting with Bundle:: Bundle \& everything else Module or Author .Ve .PP Modules know their associated Distribution objects. They always refer to the most recent official release. Developers may mark their releases as unstable development versions (by inserting an underscore into the module version number which will also be reflected in the distribution name when you run 'make dist'), so the really hottest and newest distribution is not always the default. If a module Foo circulates on \s-1CPAN\s0 in both version 1.23 and 1.23_90, \s-1CPAN\s0.pm offers a convenient way to install version 1.23 by saying .PP .Vb 1 \& install Foo .Ve .PP This would install the complete distribution file (say BAR/Foo\-1.23.tar.gz) with all accompanying material. But if you would like to install version 1.23_90, you need to know where the distribution file resides on \s-1CPAN\s0 relative to the authors/id/ directory. If the author is \s-1BAR,\s0 this might be BAR/Foo\-1.23_90.tar.gz; so you would have to say .PP .Vb 1 \& install BAR/Foo\-1.23_90.tar.gz .Ve .PP The first example will be driven by an object of the class CPAN::Module, the second by an object of class CPAN::Distribution. .SS "Integrating local directories" .IX Subsection "Integrating local directories" Note: this feature is still in alpha state and may change in future versions of \s-1CPAN\s0.pm .PP Distribution objects are normally distributions from the \s-1CPAN,\s0 but there is a slightly degenerate case for Distribution objects, too, of projects held on the local disk. These distribution objects have the same name as the local directory and end with a dot. A dot by itself is also allowed for the current directory at the time \s-1CPAN\s0.pm was used. All actions such as \f(CW\*(C`make\*(C'\fR, \f(CW\*(C`test\*(C'\fR, and \f(CW\*(C`install\*(C'\fR are applied directly to that directory. This gives the command \f(CW\*(C`cpan .\*(C'\fR an interesting touch: while the normal mantra of installing a \s-1CPAN\s0 module without \s-1CPAN\s0.pm is one of .PP .Vb 5 \& perl Makefile.PL perl Build.PL \& ( go and get prerequisites ) \& make ./Build \& make test ./Build test \& make install ./Build install .Ve .PP the command \f(CW\*(C`cpan .\*(C'\fR does all of this at once. It figures out which of the two mantras is appropriate, fetches and installs all prerequisites, takes care of them recursively, and finally finishes the installation of the module in the current directory, be it a \s-1CPAN\s0 module or not. .PP The typical usage case is for private modules or working copies of projects from remote repositories on the local disk. .SS "Redirection" .IX Subsection "Redirection" The usual shell redirection symbols \f(CW\*(C` | \*(C'\fR and \f(CW\*(C`>\*(C'\fR are recognized by the cpan shell \fBonly when surrounded by whitespace\fR. So piping to pager or redirecting output into a file works somewhat as in a normal shell, with the stipulation that you must type extra spaces. .SS "Plugin support ***EXPERIMENTAL***" .IX Subsection "Plugin support ***EXPERIMENTAL***" Plugins are objects that implement any of currently eight methods: .PP .Vb 8 \& pre_get \& post_get \& pre_make \& post_make \& pre_test \& post_test \& pre_install \& post_install .Ve .PP The \f(CW\*(C`plugin_list\*(C'\fR configuration parameter holds a list of strings of the form .PP .Vb 1 \& Modulename=arg0,arg1,arg2,arg3,... .Ve .PP eg: .PP .Vb 1 \& CPAN::Plugin::Flurb=dir,/opt/pkgs/flurb/raw,verbose,1 .Ve .PP At run time, each listed plugin is instantiated as a singleton object by running the equivalent of this pseudo code: .PP .Vb 3 \& my $plugin = ; \& ; \& my $p = $instance{$plugin} ||= Modulename\->new($arg0,$arg1,...); .Ve .PP The generated singletons are kept around from instantiation until the end of the shell session. can be reconfigured at any time at run time. While the cpan shell is running, it checks all activated plugins at each of the 8 reference points listed above and runs the respective method if it is implemented for that object. The method is called with the active CPAN::Distribution object passed in as an argument. .SH "CONFIGURATION" .IX Header "CONFIGURATION" When the \s-1CPAN\s0 module is used for the first time, a configuration dialogue tries to determine a couple of site specific options. The result of the dialog is stored in a hash reference \f(CW $CPAN::Config \fR in a file CPAN/Config.pm. .PP Default values defined in the CPAN/Config.pm file can be overridden in a user specific file: CPAN/MyConfig.pm. Such a file is best placed in \f(CW\*(C`$HOME/.cpan/CPAN/MyConfig.pm\*(C'\fR, because \f(CW\*(C`$HOME/.cpan\*(C'\fR is added to the search path of the \s-1CPAN\s0 module before the \fBuse()\fR or \&\fBrequire()\fR statements. The mkmyconfig command writes this file for you. .PP The \f(CW\*(C`o conf\*(C'\fR command has various bells and whistles: .IP "completion support" 4 .IX Item "completion support" If you have a ReadLine module installed, you can hit \s-1TAB\s0 at any point of the commandline and \f(CW\*(C`o conf\*(C'\fR will offer you completion for the built-in subcommands and/or config variable names. .IP "displaying some help: o conf help" 4 .IX Item "displaying some help: o conf help" Displays a short help .IP "displaying current values: o conf [\s-1KEY\s0]" 4 .IX Item "displaying current values: o conf [KEY]" Displays the current value(s) for this config variable. Without \s-1KEY,\s0 displays all subcommands and config variables. .Sp Example: .Sp .Vb 1 \& o conf shell .Ve .Sp If \s-1KEY\s0 starts and ends with a slash, the string in between is treated as a regular expression and only keys matching this regexp are displayed .Sp Example: .Sp .Vb 1 \& o conf /color/ .Ve .IP "changing of scalar values: o conf \s-1KEY VALUE\s0" 4 .IX Item "changing of scalar values: o conf KEY VALUE" Sets the config variable \s-1KEY\s0 to \s-1VALUE.\s0 The empty string can be specified as usual in shells, with \f(CW\*(Aq\*(Aq\fR or \f(CW""\fR .Sp Example: .Sp .Vb 1 \& o conf wget /usr/bin/wget .Ve .IP "changing of list values: o conf \s-1KEY\s0 SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST" 4 .IX Item "changing of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST" If a config variable name ends with \f(CW\*(C`list\*(C'\fR, it is a list. \f(CW\*(C`o conf KEY shift\*(C'\fR removes the first element of the list, \f(CW\*(C`o conf KEY pop\*(C'\fR removes the last element of the list. \f(CW\*(C`o conf KEYS unshift LIST\*(C'\fR prepends a list of values to the list, \f(CW\*(C`o conf KEYS push LIST\*(C'\fR appends a list of valued to the list. .Sp Likewise, \f(CW\*(C`o conf KEY splice LIST\*(C'\fR passes the \s-1LIST\s0 to the corresponding splice command. .Sp Finally, any other list of arguments is taken as a new list value for the \s-1KEY\s0 variable discarding the previous value. .Sp Examples: .Sp .Vb 3 \& o conf urllist unshift http://cpan.dev.local/CPAN \& o conf urllist splice 3 1 \& o conf urllist http://cpan1.local http://cpan2.local ftp://ftp.perl.org .Ve .IP "reverting to saved: o conf defaults" 4 .IX Item "reverting to saved: o conf defaults" Reverts all config variables to the state in the saved config file. .IP "saving the config: o conf commit" 4 .IX Item "saving the config: o conf commit" Saves all config variables to the current config file (CPAN/Config.pm or CPAN/MyConfig.pm that was loaded at start). .PP The configuration dialog can be started any time later again by issuing the command \f(CW\*(C` o conf init \*(C'\fR in the \s-1CPAN\s0 shell. A subset of the configuration dialog can be run by issuing \f(CW\*(C`o conf init WORD\*(C'\fR where \s-1WORD\s0 is any valid config variable or a regular expression. .SS "Config Variables" .IX Subsection "Config Variables" The following keys in the hash reference \f(CW$CPAN::Config\fR are currently defined: .PP .Vb 10 \& allow_installing_module_downgrades \& allow or disallow installing module downgrades \& allow_installing_outdated_dists \& allow or disallow installing modules that are \& indexed in the cpan index pointing to a distro \& with a higher distro\-version number \& applypatch path to external prg \& auto_commit commit all changes to config variables to disk \& build_cache size of cache for directories to build modules \& build_dir locally accessible directory to build modules \& build_dir_reuse boolean if distros in build_dir are persistent \& build_requires_install_policy \& to install or not to install when a module is \& only needed for building. yes|no|ask/yes|ask/no \& bzip2 path to external prg \& cache_metadata use serializer to cache metadata \& check_sigs if signatures should be verified \& cleanup_after_install \& remove build directory immediately after a \& successful install and remember that for the \& duration of the session \& colorize_debug Term::ANSIColor attributes for debugging output \& colorize_output boolean if Term::ANSIColor should colorize output \& colorize_print Term::ANSIColor attributes for normal output \& colorize_warn Term::ANSIColor attributes for warnings \& commandnumber_in_prompt \& boolean if you want to see current command number \& commands_quote preferred character to use for quoting external \& commands when running them. Defaults to double \& quote on Windows, single tick everywhere else; \& can be set to space to disable quoting \& connect_to_internet_ok \& whether to ask if opening a connection is ok before \& urllist is specified \& cpan_home local directory reserved for this package \& curl path to external prg \& dontload_hash DEPRECATED \& dontload_list arrayref: modules in the list will not be \& loaded by the CPAN::has_inst() routine \& ftp path to external prg \& ftp_passive if set, the environment variable FTP_PASSIVE is set \& for downloads \& ftp_proxy proxy host for ftp requests \& ftpstats_period max number of days to keep download statistics \& ftpstats_size max number of items to keep in the download statistics \& getcwd see below \& gpg path to external prg \& gzip location of external program gzip \& halt_on_failure stop processing after the first failure of queued \& items or dependencies \& histfile file to maintain history between sessions \& histsize maximum number of lines to keep in histfile \& http_proxy proxy host for http requests \& inactivity_timeout breaks interactive Makefile.PLs or Build.PLs \& after this many seconds inactivity. Set to 0 to \& disable timeouts. \& index_expire refetch index files after this many days \& inhibit_startup_message \& if true, suppress the startup message \& keep_source_where directory in which to keep the source (if we do) \& load_module_verbosity \& report loading of optional modules used by CPAN.pm \& lynx path to external prg \& make location of external make program \& make_arg arguments that should always be passed to \*(Aqmake\*(Aq \& make_install_make_command \& the make command for running \*(Aqmake install\*(Aq, for \& example \*(Aqsudo make\*(Aq \& make_install_arg same as make_arg for \*(Aqmake install\*(Aq \& makepl_arg arguments passed to \*(Aqperl Makefile.PL\*(Aq \& mbuild_arg arguments passed to \*(Aq./Build\*(Aq \& mbuild_install_arg arguments passed to \*(Aq./Build install\*(Aq \& mbuild_install_build_command \& command to use instead of \*(Aq./Build\*(Aq when we are \& in the install stage, for example \*(Aqsudo ./Build\*(Aq \& mbuildpl_arg arguments passed to \*(Aqperl Build.PL\*(Aq \& ncftp path to external prg \& ncftpget path to external prg \& no_proxy don\*(Aqt proxy to these hosts/domains (comma separated list) \& pager location of external program more (or any pager) \& password your password if you CPAN server wants one \& patch path to external prg \& patches_dir local directory containing patch files \& perl5lib_verbosity verbosity level for PERL5LIB additions \& plugin_list list of active hooks (see Plugin support above \& and the CPAN::Plugin module) \& prefer_external_tar \& per default all untar operations are done with \& Archive::Tar; by setting this variable to true \& the external tar command is used if available \& prefer_installer legal values are MB and EUMM: if a module comes \& with both a Makefile.PL and a Build.PL, use the \& former (EUMM) or the latter (MB); if the module \& comes with only one of the two, that one will be \& used no matter the setting \& prerequisites_policy \& what to do if you are missing module prerequisites \& (\*(Aqfollow\*(Aq automatically, \*(Aqask\*(Aq me, or \*(Aqignore\*(Aq) \& For \*(Aqfollow\*(Aq, also sets PERL_AUTOINSTALL and \& PERL_EXTUTILS_AUTOINSTALL for "\-\-defaultdeps" if \& not already set \& prefs_dir local directory to store per\-distro build options \& proxy_user username for accessing an authenticating proxy \& proxy_pass password for accessing an authenticating proxy \& pushy_https use https to cpan.org when possible, otherwise use http \& to cpan.org and issue a warning \& randomize_urllist add some randomness to the sequence of the urllist \& recommends_policy whether recommended prerequisites should be included \& scan_cache controls scanning of cache (\*(Aqatstart\*(Aq, \*(Aqatexit\*(Aq or \*(Aqnever\*(Aq) \& shell your favorite shell \& show_unparsable_versions \& boolean if r command tells which modules are versionless \& show_upload_date boolean if commands should try to determine upload date \& show_zero_versions boolean if r command tells for which modules $version==0 \& suggests_policy whether suggested prerequisites should be included \& tar location of external program tar \& tar_verbosity verbosity level for the tar command \& term_is_latin deprecated: if true Unicode is translated to ISO\-8859\-1 \& (and nonsense for characters outside latin range) \& term_ornaments boolean to turn ReadLine ornamenting on/off \& test_report email test reports (if CPAN::Reporter is installed) \& trust_test_report_history \& skip testing when previously tested ok (according to \& CPAN::Reporter history) \& unzip location of external program unzip \& urllist arrayref to nearby CPAN sites (or equivalent locations) \& urllist_ping_external \& use external ping command when autoselecting mirrors \& urllist_ping_verbose \& increase verbosity when autoselecting mirrors \& use_prompt_default set PERL_MM_USE_DEFAULT for configure/make/test/install \& use_sqlite use CPAN::SQLite for metadata storage (fast and lean) \& username your username if you CPAN server wants one \& version_timeout stops version parsing after this many seconds. \& Default is 15 secs. Set to 0 to disable. \& wait_list arrayref to a wait server to try (See CPAN::WAIT) \& wget path to external prg \& yaml_load_code enable YAML code deserialisation via CPAN::DeferredCode \& yaml_module which module to use to read/write YAML files .Ve .PP You can set and query each of these options interactively in the cpan shell with the \f(CW\*(C`o conf\*(C'\fR or the \f(CW\*(C`o conf init\*(C'\fR command as specified below. .ie n .IP """o conf """ 2 .el .IP "\f(CWo conf \fR" 2 .IX Item "o conf " prints the current value of the \fIscalar option\fR .ie n .IP """o conf """ 2 .el .IP "\f(CWo conf \fR" 2 .IX Item "o conf " Sets the value of the \fIscalar option\fR to \fIvalue\fR .ie n .IP """o conf """ 2 .el .IP "\f(CWo conf \fR" 2 .IX Item "o conf " prints the current value of the \fIlist option\fR in MakeMaker's neatvalue format. .ie n .IP """o conf [shift|pop]""" 2 .el .IP "\f(CWo conf [shift|pop]\fR" 2 .IX Item "o conf [shift|pop]" shifts or pops the array in the \fIlist option\fR variable .ie n .IP """o conf [unshift|push|splice] """ 2 .el .IP "\f(CWo conf [unshift|push|splice] \fR" 2 .IX Item "o conf [unshift|push|splice] " works like the corresponding perl commands. .IP "interactive editing: o conf init [MATCH|LIST]" 2 .IX Item "interactive editing: o conf init [MATCH|LIST]" Runs an interactive configuration dialog for matching variables. Without argument runs the dialog over all supported config variables. To specify a \s-1MATCH\s0 the argument must be enclosed by slashes. .Sp Examples: .Sp .Vb 2 \& o conf init ftp_passive ftp_proxy \& o conf init /color/ .Ve .Sp Note: this method of setting config variables often provides more explanation about the functioning of a variable than the manpage. .SS "CPAN::anycwd($path): Note on config variable getcwd" .IX Subsection "CPAN::anycwd($path): Note on config variable getcwd" \&\s-1CPAN\s0.pm changes the current working directory often and needs to determine its own current working directory. By default it uses Cwd::cwd, but if for some reason this doesn't work on your system, configure alternatives according to the following table: .IP "cwd" 4 .IX Item "cwd" Calls Cwd::cwd .IP "getcwd" 4 .IX Item "getcwd" Calls Cwd::getcwd .IP "fastcwd" 4 .IX Item "fastcwd" Calls Cwd::fastcwd .IP "getdcwd" 4 .IX Item "getdcwd" Calls Cwd::getdcwd .IP "backtickcwd" 4 .IX Item "backtickcwd" Calls the external command cwd. .SS "Note on the format of the urllist parameter" .IX Subsection "Note on the format of the urllist parameter" urllist parameters are URLs according to \s-1RFC 1738.\s0 We do a little guessing if your \s-1URL\s0 is not compliant, but if you have problems with \&\f(CW\*(C`file\*(C'\fR URLs, please try the correct format. Either: .PP .Vb 1 \& file://localhost/whatever/ftp/pub/CPAN/ .Ve .PP or .PP .Vb 1 \& file:///home/ftp/pub/CPAN/ .Ve .SS "The urllist parameter has CD-ROM support" .IX Subsection "The urllist parameter has CD-ROM support" The \f(CW\*(C`urllist\*(C'\fR parameter of the configuration table contains a list of URLs used for downloading. If the list contains any \&\f(CW\*(C`file\*(C'\fR URLs, \s-1CPAN\s0 always tries there first. This feature is disabled for index files. So the recommendation for the owner of a CD-ROM with \s-1CPAN\s0 contents is: include your local, possibly outdated CD-ROM as a \f(CW\*(C`file\*(C'\fR \s-1URL\s0 at the end of urllist, e.g. .PP .Vb 1 \& o conf urllist push file://localhost/CDROM/CPAN .Ve .PP \&\s-1CPAN\s0.pm will then fetch the index files from one of the \s-1CPAN\s0 sites that come at the beginning of urllist. It will later check for each module to see whether there is a local copy of the most recent version. .PP Another peculiarity of urllist is that the site that we could successfully fetch the last file from automatically gets a preference token and is tried as the first site for the next request. So if you add a new site at runtime it may happen that the previously preferred site will be tried another time. This means that if you want to disallow a site for the next transfer, it must be explicitly removed from urllist. .SS "Maintaining the urllist parameter" .IX Subsection "Maintaining the urllist parameter" If you have \s-1YAML\s0.pm (or some other \s-1YAML\s0 module configured in \&\f(CW\*(C`yaml_module\*(C'\fR) installed, \s-1CPAN\s0.pm collects a few statistical data about recent downloads. You can view the statistics with the \f(CW\*(C`hosts\*(C'\fR command or inspect them directly by looking into the \f(CW\*(C`FTPstats.yml\*(C'\fR file in your \f(CW\*(C`cpan_home\*(C'\fR directory. .PP To get some interesting statistics, it is recommended that \&\f(CW\*(C`randomize_urllist\*(C'\fR be set; this introduces some amount of randomness into the \s-1URL\s0 selection. .ie n .SS "The ""requires"" and ""build_requires"" dependency declarations" .el .SS "The \f(CWrequires\fP and \f(CWbuild_requires\fP dependency declarations" .IX Subsection "The requires and build_requires dependency declarations" Since \s-1CPAN\s0.pm version 1.88_51 modules declared as \f(CW\*(C`build_requires\*(C'\fR by a distribution are treated differently depending on the config variable \f(CW\*(C`build_requires_install_policy\*(C'\fR. By setting \&\f(CW\*(C`build_requires_install_policy\*(C'\fR to \f(CW\*(C`no\*(C'\fR, such a module is not installed. It is only built and tested, and then kept in the list of tested but uninstalled modules. As such, it is available during the build of the dependent module by integrating the path to the \&\f(CW\*(C`blib/arch\*(C'\fR and \f(CW\*(C`blib/lib\*(C'\fR directories in the environment variable \&\s-1PERL5LIB.\s0 If \f(CW\*(C`build_requires_install_policy\*(C'\fR is set to \f(CW\*(C`yes\*(C'\fR, then both modules declared as \f(CW\*(C`requires\*(C'\fR and those declared as \&\f(CW\*(C`build_requires\*(C'\fR are treated alike. By setting to \f(CW\*(C`ask/yes\*(C'\fR or \&\f(CW\*(C`ask/no\*(C'\fR, \s-1CPAN\s0.pm asks the user and sets the default accordingly. .SS "Configuration of the allow_installing_* parameters" .IX Subsection "Configuration of the allow_installing_* parameters" The \f(CW\*(C`allow_installing_*\*(C'\fR parameters are evaluated during the \f(CW\*(C`make\*(C'\fR phase. If set to \f(CW\*(C`yes\*(C'\fR, they allow the testing and the installation of the current distro and otherwise have no effect. If set to \f(CW\*(C`no\*(C'\fR, they may abort the build (preventing testing and installing), depending on the contents of the \&\f(CW\*(C`blib/\*(C'\fR directory. The \f(CW\*(C`blib/\*(C'\fR directory is the directory that holds all the files that would usually be installed in the \f(CW\*(C`install\*(C'\fR phase. .PP \&\f(CW\*(C`allow_installing_outdated_dists\*(C'\fR compares the \f(CW\*(C`blib/\*(C'\fR directory with the \s-1CPAN\s0 index. If it finds something there that belongs, according to the index, to a different dist, it aborts the current build. .PP \&\f(CW\*(C`allow_installing_module_downgrades\*(C'\fR compares the \f(CW\*(C`blib/\*(C'\fR directory with already installed modules, actually their version numbers, as determined by ExtUtils::MakeMaker or equivalent. If a to-be-installed module would downgrade an already installed module, the current build is aborted. .PP An interesting twist occurs when a distroprefs document demands the installation of an outdated dist via goto while \&\f(CW\*(C`allow_installing_outdated_dists\*(C'\fR forbids it. Without additional provisions, this would let the \f(CW\*(C`allow_installing_outdated_dists\*(C'\fR win and the distroprefs lose. So the proper arrangement in such a case is to write a second distroprefs document for the distro that \f(CW\*(C`goto\*(C'\fR points to and overrule the \f(CW\*(C`cpanconfig\*(C'\fR there. E.g.: .PP .Vb 9 \& \-\-\- \& match: \& distribution: "^MAUKE/Keyword\-Simple\-0.04.tar.gz" \& goto: "MAUKE/Keyword\-Simple\-0.03.tar.gz" \& \-\-\- \& match: \& distribution: "^MAUKE/Keyword\-Simple\-0.03.tar.gz" \& cpanconfig: \& allow_installing_outdated_dists: yes .Ve .SS "Configuration for individual distributions (\fIDistroprefs\fP)" .IX Subsection "Configuration for individual distributions (Distroprefs)" (\fBNote:\fR This feature has been introduced in \s-1CPAN\s0.pm 1.8854) .PP Distributions on \s-1CPAN\s0 usually behave according to what we call the \&\s-1CPAN\s0 mantra. Or since the advent of Module::Build we should talk about two mantras: .PP .Vb 4 \& perl Makefile.PL perl Build.PL \& make ./Build \& make test ./Build test \& make install ./Build install .Ve .PP But some modules cannot be built with this mantra. They try to get some extra data from the user via the environment, extra arguments, or interactively\*(--thus disturbing the installation of large bundles like Phalanx100 or modules with many dependencies like Plagger. .PP The distroprefs system of \f(CW\*(C`CPAN.pm\*(C'\fR addresses this problem by allowing the user to specify extra informations and recipes in \s-1YAML\s0 files to either .IP "\(bu" 4 pass additional arguments to one of the four commands, .IP "\(bu" 4 set environment variables .IP "\(bu" 4 instantiate an Expect object that reads from the console, waits for some regular expressions and enters some answers .IP "\(bu" 4 temporarily override assorted \f(CW\*(C`CPAN.pm\*(C'\fR configuration variables .IP "\(bu" 4 specify dependencies the original maintainer forgot .IP "\(bu" 4 disable the installation of an object altogether .PP See the \s-1YAML\s0 and Data::Dumper files that come with the \f(CW\*(C`CPAN.pm\*(C'\fR distribution in the \f(CW\*(C`distroprefs/\*(C'\fR directory for examples. .SS "Filenames" .IX Subsection "Filenames" The \s-1YAML\s0 files themselves must have the \f(CW\*(C`.yml\*(C'\fR extension; all other files are ignored (for two exceptions see \fIFallback Data::Dumper and Storable\fR below). The containing directory can be specified in \&\f(CW\*(C`CPAN.pm\*(C'\fR in the \f(CW\*(C`prefs_dir\*(C'\fR config variable. Try \f(CW\*(C`o conf init prefs_dir\*(C'\fR in the \s-1CPAN\s0 shell to set and activate the distroprefs system. .PP Every \s-1YAML\s0 file may contain arbitrary documents according to the \s-1YAML\s0 specification, and every document is treated as an entity that can specify the treatment of a single distribution. .PP Filenames can be picked arbitrarily; \f(CW\*(C`CPAN.pm\*(C'\fR always reads all files (in alphabetical order) and takes the key \f(CW\*(C`match\*(C'\fR (see below in \fILanguage Specs\fR) as a hashref containing match criteria that determine if the current distribution matches the \s-1YAML\s0 document or not. .SS "Fallback Data::Dumper and Storable" .IX Subsection "Fallback Data::Dumper and Storable" If neither your configured \f(CW\*(C`yaml_module\*(C'\fR nor \s-1YAML\s0.pm is installed, \&\s-1CPAN\s0.pm falls back to using Data::Dumper and Storable and looks for files with the extensions \f(CW\*(C`.dd\*(C'\fR or \f(CW\*(C`.st\*(C'\fR in the \f(CW\*(C`prefs_dir\*(C'\fR directory. These files are expected to contain one or more hashrefs. For Data::Dumper generated files, this is expected to be done with by defining \f(CW$VAR1\fR, \f(CW$VAR2\fR, etc. The \s-1YAML\s0 shell would produce these with the command .PP .Vb 1 \& ysh < somefile.yml > somefile.dd .Ve .PP For Storable files the rule is that they must be constructed such that \&\f(CW\*(C`Storable::retrieve(file)\*(C'\fR returns an array reference and the array elements represent one distropref object each. The conversion from \&\s-1YAML\s0 would look like so: .PP .Vb 3 \& perl \-MYAML=LoadFile \-MStorable=nstore \-e \*(Aq \& @y=LoadFile(shift); \& nstore(\e@y, shift)\*(Aq somefile.yml somefile.st .Ve .PP In bootstrapping situations it is usually sufficient to translate only a few \s-1YAML\s0 files to Data::Dumper for crucial modules like \&\f(CW\*(C`YAML::Syck\*(C'\fR, \f(CW\*(C`YAML.pm\*(C'\fR and \f(CW\*(C`Expect.pm\*(C'\fR. If you prefer Storable over Data::Dumper, remember to pull out a Storable version that writes an older format than all the other Storable versions that will need to read them. .SS "Blueprint" .IX Subsection "Blueprint" The following example contains all supported keywords and structures with the exception of \f(CW\*(C`eexpect\*(C'\fR which can be used instead of \&\f(CW\*(C`expect\*(C'\fR. .PP .Vb 10 \& \-\-\- \& comment: "Demo" \& match: \& module: "Dancing::Queen" \& distribution: "^CHACHACHA/Dancing\-" \& not_distribution: "\e.zip$" \& perl: "/usr/local/cariba\-perl/bin/perl" \& perlconfig: \& archname: "freebsd" \& not_cc: "gcc" \& env: \& DANCING_FLOOR: "Shubiduh" \& disabled: 1 \& cpanconfig: \& make: gmake \& pl: \& args: \& \- "\-\-somearg=specialcase" \& \& env: {} \& \& expect: \& \- "Which is your favorite fruit" \& \- "apple\en" \& \& make: \& args: \& \- all \& \- extra\-all \& \& env: {} \& \& expect: [] \& \& commandline: "echo SKIPPING make" \& \& test: \& args: [] \& \& env: {} \& \& expect: [] \& \& install: \& args: [] \& \& env: \& WANT_TO_INSTALL: YES \& \& expect: \& \- "Do you really want to install" \& \- "y\en" \& \& patches: \& \- "ABCDE/Fedcba\-3.14\-ABCDE\-01.patch" \& \& depends: \& configure_requires: \& LWP: 5.8 \& build_requires: \& Test::Exception: 0.25 \& requires: \& Spiffy: 0.30 .Ve .SS "Language Specs" .IX Subsection "Language Specs" Every \s-1YAML\s0 document represents a single hash reference. The valid keys in this hash are as follows: .IP "comment [scalar]" 4 .IX Item "comment [scalar]" A comment .IP "cpanconfig [hash]" 4 .IX Item "cpanconfig [hash]" Temporarily override assorted \f(CW\*(C`CPAN.pm\*(C'\fR configuration variables. .Sp Supported are: \f(CW\*(C`build_requires_install_policy\*(C'\fR, \f(CW\*(C`check_sigs\*(C'\fR, \&\f(CW\*(C`make\*(C'\fR, \f(CW\*(C`make_install_make_command\*(C'\fR, \f(CW\*(C`prefer_installer\*(C'\fR, \&\f(CW\*(C`test_report\*(C'\fR. Please report as a bug when you need another one supported. .IP "depends [hash] *** \s-1EXPERIMENTAL FEATURE\s0 ***" 4 .IX Item "depends [hash] *** EXPERIMENTAL FEATURE ***" All three types, namely \f(CW\*(C`configure_requires\*(C'\fR, \f(CW\*(C`build_requires\*(C'\fR, and \&\f(CW\*(C`requires\*(C'\fR are supported in the way specified in the \s-1META\s0.yml specification. The current implementation \fImerges\fR the specified dependencies with those declared by the package maintainer. In a future implementation this may be changed to override the original declaration. .IP "disabled [boolean]" 4 .IX Item "disabled [boolean]" Specifies that this distribution shall not be processed at all. .IP "features [array] *** \s-1EXPERIMENTAL FEATURE\s0 ***" 4 .IX Item "features [array] *** EXPERIMENTAL FEATURE ***" Experimental implementation to deal with optional_features from \&\s-1META\s0.yml. Still needs coordination with installer software and currently works only for \s-1META\s0.yml declaring \f(CW\*(C`dynamic_config=0\*(C'\fR. Use with caution. .IP "goto [string]" 4 .IX Item "goto [string]" The canonical name of a delegate distribution to install instead. Useful when a new version, although it tests \s-1OK\s0 itself, breaks something else or a developer release or a fork is already uploaded that is better than the last released version. .IP "install [hash]" 4 .IX Item "install [hash]" Processing instructions for the \f(CW\*(C`make install\*(C'\fR or \f(CW\*(C`./Build install\*(C'\fR phase of the \s-1CPAN\s0 mantra. See below under \fIProcessing Instructions\fR. .IP "make [hash]" 4 .IX Item "make [hash]" Processing instructions for the \f(CW\*(C`make\*(C'\fR or \f(CW\*(C`./Build\*(C'\fR phase of the \&\s-1CPAN\s0 mantra. See below under \fIProcessing Instructions\fR. .IP "match [hash]" 4 .IX Item "match [hash]" A hashref with one or more of the keys \f(CW\*(C`distribution\*(C'\fR, \f(CW\*(C`module\*(C'\fR, \&\f(CW\*(C`perl\*(C'\fR, \f(CW\*(C`perlconfig\*(C'\fR, and \f(CW\*(C`env\*(C'\fR that specify whether a document is targeted at a specific \s-1CPAN\s0 distribution or installation. Keys prefixed with \f(CW\*(C`not_\*(C'\fR negates the corresponding match. .Sp The corresponding values are interpreted as regular expressions. The \&\f(CW\*(C`distribution\*(C'\fR related one will be matched against the canonical distribution name, e.g. \*(L"AUTHOR/Foo\-Bar\-3.14.tar.gz\*(R". .Sp The \f(CW\*(C`module\*(C'\fR related one will be matched against \fIall\fR modules contained in the distribution until one module matches. .Sp The \f(CW\*(C`perl\*(C'\fR related one will be matched against \f(CW$^X\fR (but with the absolute path). .Sp The value associated with \f(CW\*(C`perlconfig\*(C'\fR is itself a hashref that is matched against corresponding values in the \f(CW%Config::Config\fR hash living in the \f(CW\*(C`Config.pm\*(C'\fR module. Keys prefixed with \f(CW\*(C`not_\*(C'\fR negates the corresponding match. .Sp The value associated with \f(CW\*(C`env\*(C'\fR is itself a hashref that is matched against corresponding values in the \f(CW%ENV\fR hash. Keys prefixed with \f(CW\*(C`not_\*(C'\fR negates the corresponding match. .Sp If more than one restriction of \f(CW\*(C`module\*(C'\fR, \f(CW\*(C`distribution\*(C'\fR, etc. is specified, the results of the separately computed match values must all match. If so, the hashref represented by the \&\s-1YAML\s0 document is returned as the preference structure for the current distribution. .IP "patches [array]" 4 .IX Item "patches [array]" An array of patches on \s-1CPAN\s0 or on the local disk to be applied in order via an external patch program. If the value for the \f(CW\*(C`\-p\*(C'\fR parameter is \f(CW0\fR or \f(CW1\fR is determined by reading the patch beforehand. The path to each patch is either an absolute path on the local filesystem or relative to a patch directory specified in the \&\f(CW\*(C`patches_dir\*(C'\fR configuration variable or in the format of a canonical distro name. For examples please consult the distroprefs/ directory in the \s-1CPAN\s0.pm distribution (these examples are not installed by default). .Sp Note: if the \f(CW\*(C`applypatch\*(C'\fR program is installed and \f(CW\*(C`CPAN::Config\*(C'\fR knows about it \fBand\fR a patch is written by the \f(CW\*(C`makepatch\*(C'\fR program, then \f(CW\*(C`CPAN.pm\*(C'\fR lets \f(CW\*(C`applypatch\*(C'\fR apply the patch. Both \f(CW\*(C`makepatch\*(C'\fR and \f(CW\*(C`applypatch\*(C'\fR are available from \s-1CPAN\s0 in the \f(CW\*(C`JV/makepatch\-*\*(C'\fR distribution. .IP "pl [hash]" 4 .IX Item "pl [hash]" Processing instructions for the \f(CW\*(C`perl Makefile.PL\*(C'\fR or \f(CW\*(C`perl Build.PL\*(C'\fR phase of the \s-1CPAN\s0 mantra. See below under \fIProcessing Instructions\fR. .IP "test [hash]" 4 .IX Item "test [hash]" Processing instructions for the \f(CW\*(C`make test\*(C'\fR or \f(CW\*(C`./Build test\*(C'\fR phase of the \s-1CPAN\s0 mantra. See below under \fIProcessing Instructions\fR. .SS "Processing Instructions" .IX Subsection "Processing Instructions" .IP "args [array]" 4 .IX Item "args [array]" Arguments to be added to the command line .IP "commandline" 4 .IX Item "commandline" A full commandline to run via \f(CW\*(C`system()\*(C'\fR. During execution, the environment variable \s-1PERL\s0 is set to $^X (but with an absolute path). If \f(CW\*(C`commandline\*(C'\fR is specified, \&\f(CW\*(C`args\*(C'\fR is not used. .IP "eexpect [hash]" 4 .IX Item "eexpect [hash]" Extended \f(CW\*(C`expect\*(C'\fR. This is a hash reference with four allowed keys, \&\f(CW\*(C`mode\*(C'\fR, \f(CW\*(C`timeout\*(C'\fR, \f(CW\*(C`reuse\*(C'\fR, and \f(CW\*(C`talk\*(C'\fR. .Sp You must install the \f(CW\*(C`Expect\*(C'\fR module to use \f(CW\*(C`eexpect\*(C'\fR. \s-1CPAN\s0.pm does not install it for you. .Sp \&\f(CW\*(C`mode\*(C'\fR may have the values \f(CW\*(C`deterministic\*(C'\fR for the case where all questions come in the order written down and \f(CW\*(C`anyorder\*(C'\fR for the case where the questions may come in any order. The default mode is \&\f(CW\*(C`deterministic\*(C'\fR. .Sp \&\f(CW\*(C`timeout\*(C'\fR denotes a timeout in seconds. Floating-point timeouts are \&\s-1OK.\s0 With \f(CW\*(C`mode=deterministic\*(C'\fR, the timeout denotes the timeout per question; with \f(CW\*(C`mode=anyorder\*(C'\fR it denotes the timeout per byte received from the stream or questions. .Sp \&\f(CW\*(C`talk\*(C'\fR is a reference to an array that contains alternating questions and answers. Questions are regular expressions and answers are literal strings. The Expect module watches the stream from the execution of the external program (\f(CW\*(C`perl Makefile.PL\*(C'\fR, \f(CW\*(C`perl Build.PL\*(C'\fR, \f(CW\*(C`make\*(C'\fR, etc.). .Sp For \f(CW\*(C`mode=deterministic\*(C'\fR, the \s-1CPAN\s0.pm injects the corresponding answer as soon as the stream matches the regular expression. .Sp For \f(CW\*(C`mode=anyorder\*(C'\fR \s-1CPAN\s0.pm answers a question as soon as the timeout is reached for the next byte in the input stream. In this mode you can use the \f(CW\*(C`reuse\*(C'\fR parameter to decide what will happen with a question-answer pair after it has been used. In the default case (reuse=0) it is removed from the array, avoiding being used again accidentally. If you want to answer the question \f(CW\*(C`Do you really want to do that\*(C'\fR several times, then it must be included in the array at least as often as you want this answer to be given. Setting the parameter \f(CW\*(C`reuse\*(C'\fR to 1 makes this repetition unnecessary. .IP "env [hash]" 4 .IX Item "env [hash]" Environment variables to be set during the command .IP "expect [array]" 4 .IX Item "expect [array]" You must install the \f(CW\*(C`Expect\*(C'\fR module to use \f(CW\*(C`expect\*(C'\fR. \s-1CPAN\s0.pm does not install it for you. .Sp \&\f(CW\*(C`expect: \*(C'\fR is a short notation for this \f(CW\*(C`eexpect\*(C'\fR: .Sp .Vb 4 \& eexpect: \& mode: deterministic \& timeout: 15 \& talk: .Ve .ie n .SS "Schema verification with ""Kwalify""" .el .SS "Schema verification with \f(CWKwalify\fP" .IX Subsection "Schema verification with Kwalify" If you have the \f(CW\*(C`Kwalify\*(C'\fR module installed (which is part of the Bundle::CPANxxl), then all your distroprefs files are checked for syntactic correctness. .SS "Example Distroprefs Files" .IX Subsection "Example Distroprefs Files" \&\f(CW\*(C`CPAN.pm\*(C'\fR comes with a collection of example \s-1YAML\s0 files. Note that these are really just examples and should not be used without care because they cannot fit everybody's purpose. After all, the authors of the packages that ask questions had a need to ask, so you should watch their questions and adjust the examples to your environment and your needs. You have been warned:\-) .SH "PROGRAMMER'S INTERFACE" .IX Header "PROGRAMMER'S INTERFACE" If you do not enter the shell, shell commands are available both as methods (\f(CW\*(C`CPAN::Shell\->install(...)\*(C'\fR) and as functions in the calling package (\f(CW\*(C`install(...)\*(C'\fR). Before calling low-level commands, it makes sense to initialize components of \s-1CPAN\s0 you need, e.g.: .PP .Vb 3 \& CPAN::HandleConfig\->load; \& CPAN::Shell::setup_output; \& CPAN::Index\->reload; .Ve .PP High-level commands do such initializations automatically. .PP There's currently only one class that has a stable interface \- CPAN::Shell. All commands that are available in the \s-1CPAN\s0 shell are methods of the class CPAN::Shell. The arguments on the commandline are passed as arguments to the method. .PP So if you take for example the shell command .PP .Vb 1 \& notest install A B C .Ve .PP the actually executed command is .PP .Vb 1 \& CPAN::Shell\->notest("install","A","B","C"); .Ve .PP Each of the commands that produce listings of modules (\f(CW\*(C`r\*(C'\fR, \&\f(CW\*(C`autobundle\*(C'\fR, \f(CW\*(C`u\*(C'\fR) also return a list of the IDs of all modules within the list. .IP "expand($type,@things)" 2 .IX Item "expand($type,@things)" The IDs of all objects available within a program are strings that can be expanded to the corresponding real objects with the \&\f(CW\*(C`CPAN::Shell\->expand("Module",@things)\*(C'\fR method. Expand returns a list of CPAN::Module objects according to the \f(CW@things\fR arguments given. In scalar context, it returns only the first element of the list. .IP "expandany(@things)" 2 .IX Item "expandany(@things)" Like expand, but returns objects of the appropriate type, i.e. CPAN::Bundle objects for bundles, CPAN::Module objects for modules, and CPAN::Distribution objects for distributions. Note: it does not expand to CPAN::Author objects. .IP "Programming Examples" 2 .IX Item "Programming Examples" This enables the programmer to do operations that combine functionalities that are available in the shell. .Sp .Vb 2 \& # install everything that is outdated on my disk: \& perl \-MCPAN \-e \*(AqCPAN::Shell\->install(CPAN::Shell\->r)\*(Aq \& \& # install my favorite programs if necessary: \& for $mod (qw(Net::FTP Digest::SHA Data::Dumper)) { \& CPAN::Shell\->install($mod); \& } \& \& # list all modules on my disk that have no VERSION number \& for $mod (CPAN::Shell\->expand("Module","/./")) { \& next unless $mod\->inst_file; \& # MakeMaker convention for undefined $VERSION: \& next unless $mod\->inst_version eq "undef"; \& print "No VERSION in ", $mod\->id, "\en"; \& } \& \& # find out which distribution on CPAN contains a module: \& print CPAN::Shell\->expand("Module","Apache::Constants")\->cpan_file .Ve .Sp Or if you want to schedule a \fIcron\fR job to watch \s-1CPAN,\s0 you could list all modules that need updating. First a quick and dirty way: .Sp .Vb 1 \& perl \-e \*(Aquse CPAN; CPAN::Shell\->r;\*(Aq .Ve .Sp If you don't want any output should all modules be up to date, parse the output of above command for the regular expression \f(CW\*(C`/modules are up to date/\*(C'\fR and decide to mail the output only if it doesn't match. .Sp If you prefer to do it more in a programmerish style in one single process, something like this may better suit you: .Sp .Vb 7 \& # list all modules on my disk that have newer versions on CPAN \& for $mod (CPAN::Shell\->expand("Module","/./")) { \& next unless $mod\->inst_file; \& next if $mod\->uptodate; \& printf "Module %s is installed as %s, could be updated to %s from CPAN\en", \& $mod\->id, $mod\->inst_version, $mod\->cpan_version; \& } .Ve .Sp If that gives too much output every day, you may want to watch only for three modules. You can write .Sp .Vb 1 \& for $mod (CPAN::Shell\->expand("Module","/Apache|LWP|CGI/")) { .Ve .Sp as the first line instead. Or you can combine some of the above tricks: .Sp .Vb 5 \& # watch only for a new mod_perl module \& $mod = CPAN::Shell\->expand("Module","mod_perl"); \& exit if $mod\->uptodate; \& # new mod_perl arrived, let me know all update recommendations \& CPAN::Shell\->r; .Ve .SS "Methods in the other Classes" .IX Subsection "Methods in the other Classes" .IP "\fBCPAN::Author::as_glimpse()\fR" 4 .IX Item "CPAN::Author::as_glimpse()" Returns a one-line description of the author .IP "\fBCPAN::Author::as_string()\fR" 4 .IX Item "CPAN::Author::as_string()" Returns a multi-line description of the author .IP "\fBCPAN::Author::email()\fR" 4 .IX Item "CPAN::Author::email()" Returns the author's email address .IP "\fBCPAN::Author::fullname()\fR" 4 .IX Item "CPAN::Author::fullname()" Returns the author's name .IP "\fBCPAN::Author::name()\fR" 4 .IX Item "CPAN::Author::name()" An alias for fullname .IP "\fBCPAN::Bundle::as_glimpse()\fR" 4 .IX Item "CPAN::Bundle::as_glimpse()" Returns a one-line description of the bundle .IP "\fBCPAN::Bundle::as_string()\fR" 4 .IX Item "CPAN::Bundle::as_string()" Returns a multi-line description of the bundle .IP "\fBCPAN::Bundle::clean()\fR" 4 .IX Item "CPAN::Bundle::clean()" Recursively runs the \f(CW\*(C`clean\*(C'\fR method on all items contained in the bundle. .IP "\fBCPAN::Bundle::contains()\fR" 4 .IX Item "CPAN::Bundle::contains()" Returns a list of objects' IDs contained in a bundle. The associated objects may be bundles, modules or distributions. .IP "CPAN::Bundle::force($method,@args)" 4 .IX Item "CPAN::Bundle::force($method,@args)" Forces \s-1CPAN\s0 to perform a task that it normally would have refused to do. Force takes as arguments a method name to be called and any number of additional arguments that should be passed to the called method. The internals of the object get the needed changes so that \s-1CPAN\s0.pm does not refuse to take the action. The \f(CW\*(C`force\*(C'\fR is passed recursively to all contained objects. See also the section above on the \f(CW\*(C`force\*(C'\fR and the \f(CW\*(C`fforce\*(C'\fR pragma. .IP "\fBCPAN::Bundle::get()\fR" 4 .IX Item "CPAN::Bundle::get()" Recursively runs the \f(CW\*(C`get\*(C'\fR method on all items contained in the bundle .IP "\fBCPAN::Bundle::inst_file()\fR" 4 .IX Item "CPAN::Bundle::inst_file()" Returns the highest installed version of the bundle in either \f(CW@INC\fR or \&\f(CW\*(C`$CPAN::Config\->{cpan_home}\*(C'\fR. Note that this is different from CPAN::Module::inst_file. .IP "\fBCPAN::Bundle::inst_version()\fR" 4 .IX Item "CPAN::Bundle::inst_version()" Like CPAN::Bundle::inst_file, but returns the \f(CW$VERSION\fR .IP "\fBCPAN::Bundle::uptodate()\fR" 4 .IX Item "CPAN::Bundle::uptodate()" Returns 1 if the bundle itself and all its members are up-to-date. .IP "\fBCPAN::Bundle::install()\fR" 4 .IX Item "CPAN::Bundle::install()" Recursively runs the \f(CW\*(C`install\*(C'\fR method on all items contained in the bundle .IP "\fBCPAN::Bundle::make()\fR" 4 .IX Item "CPAN::Bundle::make()" Recursively runs the \f(CW\*(C`make\*(C'\fR method on all items contained in the bundle .IP "\fBCPAN::Bundle::readme()\fR" 4 .IX Item "CPAN::Bundle::readme()" Recursively runs the \f(CW\*(C`readme\*(C'\fR method on all items contained in the bundle .IP "\fBCPAN::Bundle::test()\fR" 4 .IX Item "CPAN::Bundle::test()" Recursively runs the \f(CW\*(C`test\*(C'\fR method on all items contained in the bundle .IP "\fBCPAN::Distribution::as_glimpse()\fR" 4 .IX Item "CPAN::Distribution::as_glimpse()" Returns a one-line description of the distribution .IP "\fBCPAN::Distribution::as_string()\fR" 4 .IX Item "CPAN::Distribution::as_string()" Returns a multi-line description of the distribution .IP "CPAN::Distribution::author" 4 .IX Item "CPAN::Distribution::author" Returns the CPAN::Author object of the maintainer who uploaded this distribution .IP "\fBCPAN::Distribution::pretty_id()\fR" 4 .IX Item "CPAN::Distribution::pretty_id()" Returns a string of the form \*(L"\s-1AUTHORID/TARBALL\*(R",\s0 where \s-1AUTHORID\s0 is the author's \s-1PAUSE ID\s0 and \s-1TARBALL\s0 is the distribution filename. .IP "\fBCPAN::Distribution::base_id()\fR" 4 .IX Item "CPAN::Distribution::base_id()" Returns the distribution filename without any archive suffix. E.g \&\*(L"Foo\-Bar\-0.01\*(R" .IP "\fBCPAN::Distribution::clean()\fR" 4 .IX Item "CPAN::Distribution::clean()" Changes to the directory where the distribution has been unpacked and runs \f(CW\*(C`make clean\*(C'\fR there. .IP "\fBCPAN::Distribution::containsmods()\fR" 4 .IX Item "CPAN::Distribution::containsmods()" Returns a list of IDs of modules contained in a distribution file. Works only for distributions listed in the 02packages.details.txt.gz file. This typically means that just most recent version of a distribution is covered. .IP "\fBCPAN::Distribution::cvs_import()\fR" 4 .IX Item "CPAN::Distribution::cvs_import()" Changes to the directory where the distribution has been unpacked and runs something like .Sp .Vb 1 \& cvs \-d $cvs_root import \-m $cvs_log $cvs_dir $userid v$version .Ve .Sp there. .IP "\fBCPAN::Distribution::dir()\fR" 4 .IX Item "CPAN::Distribution::dir()" Returns the directory into which this distribution has been unpacked. .IP "CPAN::Distribution::force($method,@args)" 4 .IX Item "CPAN::Distribution::force($method,@args)" Forces \s-1CPAN\s0 to perform a task that it normally would have refused to do. Force takes as arguments a method name to be called and any number of additional arguments that should be passed to the called method. The internals of the object get the needed changes so that \s-1CPAN\s0.pm does not refuse to take the action. See also the section above on the \&\f(CW\*(C`force\*(C'\fR and the \f(CW\*(C`fforce\*(C'\fR pragma. .IP "\fBCPAN::Distribution::get()\fR" 4 .IX Item "CPAN::Distribution::get()" Downloads the distribution from \s-1CPAN\s0 and unpacks it. Does nothing if the distribution has already been downloaded and unpacked within the current session. .IP "\fBCPAN::Distribution::install()\fR" 4 .IX Item "CPAN::Distribution::install()" Changes to the directory where the distribution has been unpacked and runs the external command \f(CW\*(C`make install\*(C'\fR there. If \f(CW\*(C`make\*(C'\fR has not yet been run, it will be run first. A \f(CW\*(C`make test\*(C'\fR is issued in any case and if this fails, the install is cancelled. The cancellation can be avoided by letting \f(CW\*(C`force\*(C'\fR run the \f(CW\*(C`install\*(C'\fR for you. .Sp This install method only has the power to install the distribution if there are no dependencies in the way. To install an object along with all its dependencies, use CPAN::Shell\->install. .Sp Note that \fBinstall()\fR gives no meaningful return value. See \fBuptodate()\fR. .IP "\fBCPAN::Distribution::isa_perl()\fR" 4 .IX Item "CPAN::Distribution::isa_perl()" Returns 1 if this distribution file seems to be a perl distribution. Normally this is derived from the file name only, but the index from \&\s-1CPAN\s0 can contain a hint to achieve a return value of true for other filenames too. .IP "\fBCPAN::Distribution::look()\fR" 4 .IX Item "CPAN::Distribution::look()" Changes to the directory where the distribution has been unpacked and opens a subshell there. Exiting the subshell returns. .IP "\fBCPAN::Distribution::make()\fR" 4 .IX Item "CPAN::Distribution::make()" First runs the \f(CW\*(C`get\*(C'\fR method to make sure the distribution is downloaded and unpacked. Changes to the directory where the distribution has been unpacked and runs the external commands \f(CW\*(C`perl Makefile.PL\*(C'\fR or \f(CW\*(C`perl Build.PL\*(C'\fR and \f(CW\*(C`make\*(C'\fR there. .IP "\fBCPAN::Distribution::perldoc()\fR" 4 .IX Item "CPAN::Distribution::perldoc()" Downloads the pod documentation of the file associated with a distribution (in \s-1HTML\s0 format) and runs it through the external command \fIlynx\fR specified in \f(CW\*(C`$CPAN::Config\->{lynx}\*(C'\fR. If \fIlynx\fR isn't available, it converts it to plain text with the external command \fIhtml2text\fR and runs it through the pager specified in \f(CW\*(C`$CPAN::Config\->{pager}\*(C'\fR. .IP "\fBCPAN::Distribution::prefs()\fR" 4 .IX Item "CPAN::Distribution::prefs()" Returns the hash reference from the first matching \s-1YAML\s0 file that the user has deposited in the \f(CW\*(C`prefs_dir/\*(C'\fR directory. The first succeeding match wins. The files in the \f(CW\*(C`prefs_dir/\*(C'\fR are processed alphabetically, and the canonical distro name (e.g. AUTHOR/Foo\-Bar\-3.14.tar.gz) is matched against the regular expressions stored in the \f(CW$root\fR\->{match}{distribution} attribute value. Additionally all module names contained in a distribution are matched against the regular expressions in the \f(CW$root\fR\->{match}{module} attribute value. The two match values are ANDed together. Each of the two attributes are optional. .IP "\fBCPAN::Distribution::prereq_pm()\fR" 4 .IX Item "CPAN::Distribution::prereq_pm()" Returns the hash reference that has been announced by a distribution as the \f(CW\*(C`requires\*(C'\fR and \f(CW\*(C`build_requires\*(C'\fR elements. These can be declared either by the \f(CW\*(C`META.yml\*(C'\fR (if authoritative) or can be deposited after the run of \f(CW\*(C`Build.PL\*(C'\fR in the file \f(CW\*(C`./_build/prereqs\*(C'\fR or after the run of \f(CW\*(C`Makfile.PL\*(C'\fR written as the \f(CW\*(C`PREREQ_PM\*(C'\fR hash in a comment in the produced \f(CW\*(C`Makefile\*(C'\fR. \fINote\fR: this method only works after an attempt has been made to \f(CW\*(C`make\*(C'\fR the distribution. Returns undef otherwise. .IP "\fBCPAN::Distribution::readme()\fR" 4 .IX Item "CPAN::Distribution::readme()" Downloads the \s-1README\s0 file associated with a distribution and runs it through the pager specified in \f(CW\*(C`$CPAN::Config\->{pager}\*(C'\fR. .IP "\fBCPAN::Distribution::reports()\fR" 4 .IX Item "CPAN::Distribution::reports()" Downloads report data for this distribution from www.cpantesters.org and displays a subset of them. .IP "\fBCPAN::Distribution::read_yaml()\fR" 4 .IX Item "CPAN::Distribution::read_yaml()" Returns the content of the \s-1META\s0.yml of this distro as a hashref. Note: works only after an attempt has been made to \f(CW\*(C`make\*(C'\fR the distribution. Returns undef otherwise. Also returns undef if the content of \s-1META\s0.yml is not authoritative. (The rules about what exactly makes the content authoritative are still in flux.) .IP "\fBCPAN::Distribution::test()\fR" 4 .IX Item "CPAN::Distribution::test()" Changes to the directory where the distribution has been unpacked and runs \f(CW\*(C`make test\*(C'\fR there. .IP "\fBCPAN::Distribution::uptodate()\fR" 4 .IX Item "CPAN::Distribution::uptodate()" Returns 1 if all the modules contained in the distribution are up-to-date. Relies on containsmods. .IP "\fBCPAN::Index::force_reload()\fR" 4 .IX Item "CPAN::Index::force_reload()" Forces a reload of all indices. .IP "\fBCPAN::Index::reload()\fR" 4 .IX Item "CPAN::Index::reload()" Reloads all indices if they have not been read for more than \&\f(CW\*(C`$CPAN::Config\->{index_expire}\*(C'\fR days. .IP "\fBCPAN::InfoObj::dump()\fR" 4 .IX Item "CPAN::InfoObj::dump()" CPAN::Author, CPAN::Bundle, CPAN::Module, and CPAN::Distribution inherit this method. It prints the data structure associated with an object. Useful for debugging. Note: the data structure is considered internal and thus subject to change without notice. .IP "\fBCPAN::Module::as_glimpse()\fR" 4 .IX Item "CPAN::Module::as_glimpse()" Returns a one-line description of the module in four columns: The first column contains the word \f(CW\*(C`Module\*(C'\fR, the second column consists of one character: an equals sign if this module is already installed and up-to-date, a less-than sign if this module is installed but can be upgraded, and a space if the module is not installed. The third column is the name of the module and the fourth column gives maintainer or distribution information. .IP "\fBCPAN::Module::as_string()\fR" 4 .IX Item "CPAN::Module::as_string()" Returns a multi-line description of the module .IP "\fBCPAN::Module::clean()\fR" 4 .IX Item "CPAN::Module::clean()" Runs a clean on the distribution associated with this module. .IP "\fBCPAN::Module::cpan_file()\fR" 4 .IX Item "CPAN::Module::cpan_file()" Returns the filename on \s-1CPAN\s0 that is associated with the module. .IP "\fBCPAN::Module::cpan_version()\fR" 4 .IX Item "CPAN::Module::cpan_version()" Returns the latest version of this module available on \s-1CPAN.\s0 .IP "\fBCPAN::Module::cvs_import()\fR" 4 .IX Item "CPAN::Module::cvs_import()" Runs a cvs_import on the distribution associated with this module. .IP "\fBCPAN::Module::description()\fR" 4 .IX Item "CPAN::Module::description()" Returns a 44 character description of this module. Only available for modules listed in The Module List (CPAN/modules/00modlist.long.html or 00modlist.long.txt.gz) .IP "\fBCPAN::Module::distribution()\fR" 4 .IX Item "CPAN::Module::distribution()" Returns the CPAN::Distribution object that contains the current version of this module. .IP "\fBCPAN::Module::dslip_status()\fR" 4 .IX Item "CPAN::Module::dslip_status()" Returns a hash reference. The keys of the hash are the letters \f(CW\*(C`D\*(C'\fR, \&\f(CW\*(C`S\*(C'\fR, \f(CW\*(C`L\*(C'\fR, \f(CW\*(C`I\*(C'\fR, and

, for development status, support level, language, interface and public licence respectively. The data for the \&\s-1DSLIP\s0 status are collected by pause.perl.org when authors register their namespaces. The values of the 5 hash elements are one-character words whose meaning is described in the table below. There are also 5 hash elements \f(CW\*(C`DV\*(C'\fR, \f(CW\*(C`SV\*(C'\fR, \f(CW\*(C`LV\*(C'\fR, \f(CW\*(C`IV\*(C'\fR, and <\s-1PV\s0> that carry a more verbose value of the 5 status variables. .Sp Where the '\s-1DSLIP\s0' characters have the following meanings: .Sp .Vb 7 \& D \- Development Stage (Note: *NO IMPLIED TIMESCALES*): \& i \- Idea, listed to gain consensus or as a placeholder \& c \- under construction but pre\-alpha (not yet released) \& a/b \- Alpha/Beta testing \& R \- Released \& M \- Mature (no rigorous definition) \& S \- Standard, supplied with Perl 5 \& \& S \- Support Level: \& m \- Mailing\-list \& d \- Developer \& u \- Usenet newsgroup comp.lang.perl.modules \& n \- None known, try comp.lang.perl.modules \& a \- abandoned; volunteers welcome to take over maintenance \& \& L \- Language Used: \& p \- Perl\-only, no compiler needed, should be platform independent \& c \- C and perl, a C compiler will be needed \& h \- Hybrid, written in perl with optional C code, no compiler needed \& + \- C++ and perl, a C++ compiler will be needed \& o \- perl and another language other than C or C++ \& \& I \- Interface Style \& f \- plain Functions, no references used \& h \- hybrid, object and function interfaces available \& n \- no interface at all (huh?) \& r \- some use of unblessed References or ties \& O \- Object oriented using blessed references and/or inheritance \& \& P \- Public License \& p \- Standard\-Perl: user may choose between GPL and Artistic \& g \- GPL: GNU General Public License \& l \- LGPL: "GNU Lesser General Public License" (previously known as \& "GNU Library General Public License") \& b \- BSD: The BSD License \& a \- Artistic license alone \& 2 \- Artistic license 2.0 or later \& o \- open source: approved by www.opensource.org \& d \- allows distribution without restrictions \& r \- restricted distribution \& n \- no license at all .Ve .IP "CPAN::Module::force($method,@args)" 4 .IX Item "CPAN::Module::force($method,@args)" Forces \s-1CPAN\s0 to perform a task it would normally refuse to do. Force takes as arguments a method name to be invoked and any number of additional arguments to pass that method. The internals of the object get the needed changes so that \s-1CPAN\s0.pm does not refuse to take the action. See also the section above on the \&\f(CW\*(C`force\*(C'\fR and the \f(CW\*(C`fforce\*(C'\fR pragma. .IP "\fBCPAN::Module::get()\fR" 4 .IX Item "CPAN::Module::get()" Runs a get on the distribution associated with this module. .IP "\fBCPAN::Module::inst_file()\fR" 4 .IX Item "CPAN::Module::inst_file()" Returns the filename of the module found in \f(CW@INC\fR. The first file found is reported, just as perl itself stops searching \f(CW@INC\fR once it finds a module. .IP "\fBCPAN::Module::available_file()\fR" 4 .IX Item "CPAN::Module::available_file()" Returns the filename of the module found in \s-1PERL5LIB\s0 or \f(CW@INC\fR. The first file found is reported. The advantage of this method over \&\f(CW\*(C`inst_file\*(C'\fR is that modules that have been tested but not yet installed are included because \s-1PERL5LIB\s0 keeps track of tested modules. .IP "\fBCPAN::Module::inst_version()\fR" 4 .IX Item "CPAN::Module::inst_version()" Returns the version number of the installed module in readable format. .IP "\fBCPAN::Module::available_version()\fR" 4 .IX Item "CPAN::Module::available_version()" Returns the version number of the available module in readable format. .IP "\fBCPAN::Module::install()\fR" 4 .IX Item "CPAN::Module::install()" Runs an \f(CW\*(C`install\*(C'\fR on the distribution associated with this module. .IP "\fBCPAN::Module::look()\fR" 4 .IX Item "CPAN::Module::look()" Changes to the directory where the distribution associated with this module has been unpacked and opens a subshell there. Exiting the subshell returns. .IP "\fBCPAN::Module::make()\fR" 4 .IX Item "CPAN::Module::make()" Runs a \f(CW\*(C`make\*(C'\fR on the distribution associated with this module. .IP "\fBCPAN::Module::manpage_headline()\fR" 4 .IX Item "CPAN::Module::manpage_headline()" If module is installed, peeks into the module's manpage, reads the headline, and returns it. Moreover, if the module has been downloaded within this session, does the equivalent on the downloaded module even if it hasn't been installed yet. .IP "\fBCPAN::Module::perldoc()\fR" 4 .IX Item "CPAN::Module::perldoc()" Runs a \f(CW\*(C`perldoc\*(C'\fR on this module. .IP "\fBCPAN::Module::readme()\fR" 4 .IX Item "CPAN::Module::readme()" Runs a \f(CW\*(C`readme\*(C'\fR on the distribution associated with this module. .IP "\fBCPAN::Module::reports()\fR" 4 .IX Item "CPAN::Module::reports()" Calls the \fBreports()\fR method on the associated distribution object. .IP "\fBCPAN::Module::test()\fR" 4 .IX Item "CPAN::Module::test()" Runs a \f(CW\*(C`test\*(C'\fR on the distribution associated with this module. .IP "\fBCPAN::Module::uptodate()\fR" 4 .IX Item "CPAN::Module::uptodate()" Returns 1 if the module is installed and up-to-date. .IP "\fBCPAN::Module::userid()\fR" 4 .IX Item "CPAN::Module::userid()" Returns the author's \s-1ID\s0 of the module. .SS "Cache Manager" .IX Subsection "Cache Manager" Currently the cache manager only keeps track of the build directory ($CPAN::Config\->{build_dir}). It is a simple \s-1FIFO\s0 mechanism that deletes complete directories below \f(CW\*(C`build_dir\*(C'\fR as soon as the size of all directories there gets bigger than \f(CW$CPAN::Config\fR\->{build_cache} (in \s-1MB\s0). The contents of this cache may be used for later re-installations that you intend to do manually, but will never be trusted by \s-1CPAN\s0 itself. This is due to the fact that the user might use these directories for building modules on different architectures. .PP There is another directory ($CPAN::Config\->{keep_source_where}) where the original distribution files are kept. This directory is not covered by the cache manager and must be controlled by the user. If you choose to have the same directory as build_dir and as keep_source_where directory, then your sources will be deleted with the same fifo mechanism. .SS "Bundles" .IX Subsection "Bundles" A bundle is just a perl module in the namespace Bundle:: that does not define any functions or methods. It usually only contains documentation. .PP It starts like a perl module with a package declaration and a \f(CW$VERSION\fR variable. After that the pod section looks like any other pod with the only difference being that \fIone special pod section\fR exists starting with (verbatim): .PP .Vb 1 \& =head1 CONTENTS .Ve .PP In this pod section each line obeys the format .PP .Vb 1 \& Module_Name [Version_String] [\- optional text] .Ve .PP The only required part is the first field, the name of a module (e.g. Foo::Bar, i.e. \fInot\fR the name of the distribution file). The rest of the line is optional. The comment part is delimited by a dash just as in the man page header. .PP The distribution of a bundle should follow the same convention as other distributions. .PP Bundles are treated specially in the \s-1CPAN\s0 package. If you say 'install Bundle::Tkkit' (assuming such a bundle exists), \s-1CPAN\s0 will install all the modules in the \s-1CONTENTS\s0 section of the pod. You can install your own Bundles locally by placing a conformant Bundle file somewhere into your \f(CW@INC\fR path. The \fBautobundle()\fR command which is available in the shell interface does that for you by including all currently installed modules in a snapshot bundle file. .SH "PREREQUISITES" .IX Header "PREREQUISITES" The \s-1CPAN\s0 program is trying to depend on as little as possible so the user can use it in hostile environment. It works better the more goodies the environment provides. For example if you try in the \s-1CPAN\s0 shell .PP .Vb 1 \& install Bundle::CPAN .Ve .PP or .PP .Vb 1 \& install Bundle::CPANxxl .Ve .PP you will find the shell more convenient than the bare shell before. .PP If you have a local mirror of \s-1CPAN\s0 and can access all files with \&\*(L"file:\*(R" URLs, then you only need a perl later than perl5.003 to run this module. Otherwise Net::FTP is strongly recommended. \s-1LWP\s0 may be required for non-UNIX systems, or if your nearest \s-1CPAN\s0 site is associated with a \s-1URL\s0 that is not \f(CW\*(C`ftp:\*(C'\fR. .PP If you have neither Net::FTP nor \s-1LWP,\s0 there is a fallback mechanism implemented for an external ftp command or for an external lynx command. .SH "UTILITIES" .IX Header "UTILITIES" .SS "Finding packages and \s-1VERSION\s0" .IX Subsection "Finding packages and VERSION" This module presumes that all packages on \s-1CPAN\s0 .IP "\(bu" 2 declare their \f(CW$VERSION\fR variable in an easy to parse manner. This prerequisite can hardly be relaxed because it consumes far too much memory to load all packages into the running program just to determine the \f(CW$VERSION\fR variable. Currently all programs that are dealing with version use something like this .Sp .Vb 2 \& perl \-MExtUtils::MakeMaker \-le \e \& \*(Aqprint MM\->parse_version(shift)\*(Aq filename .Ve .Sp If you are author of a package and wonder if your \f(CW$VERSION\fR can be parsed, please try the above method. .IP "\(bu" 2 come as compressed or gzipped tarfiles or as zip files and contain a \&\f(CW\*(C`Makefile.PL\*(C'\fR or \f(CW\*(C`Build.PL\*(C'\fR (well, we try to handle a bit more, but with little enthusiasm). .SS "Debugging" .IX Subsection "Debugging" Debugging this module is more than a bit complex due to interference from the software producing the indices on \s-1CPAN,\s0 the mirroring process on \s-1CPAN,\s0 packaging, configuration, synchronicity, and even (gasp!) due to bugs within the \s-1CPAN\s0.pm module itself. .PP For debugging the code of \s-1CPAN\s0.pm itself in interactive mode, some debugging aid can be turned on for most packages within \&\s-1CPAN\s0.pm with one of .IP "o debug package..." 2 .IX Item "o debug package..." sets debug mode for packages. .IP "o debug \-package..." 2 .IX Item "o debug -package..." unsets debug mode for packages. .IP "o debug all" 2 .IX Item "o debug all" turns debugging on for all packages. .IP "o debug number" 2 .IX Item "o debug number" .PP which sets the debugging packages directly. Note that \f(CW\*(C`o debug 0\*(C'\fR turns debugging off. .PP What seems a successful strategy is the combination of \f(CW\*(C`reload cpan\*(C'\fR and the debugging switches. Add a new debug statement while running in the shell and then issue a \f(CW\*(C`reload cpan\*(C'\fR and see the new debugging messages immediately without losing the current context. .PP \&\f(CW\*(C`o debug\*(C'\fR without an argument lists the valid package names and the current set of packages in debugging mode. \f(CW\*(C`o debug\*(C'\fR has built-in completion support. .PP For debugging of \s-1CPAN\s0 data there is the \f(CW\*(C`dump\*(C'\fR command which takes the same arguments as make/test/install and outputs each object's Data::Dumper dump. If an argument looks like a perl variable and contains one of \f(CW\*(C`$\*(C'\fR, \f(CW\*(C`@\*(C'\fR or \f(CW\*(C`%\*(C'\fR, it is \fBeval()\fRed and fed to Data::Dumper directly. .SS "Floppy, Zip, Offline Mode" .IX Subsection "Floppy, Zip, Offline Mode" \&\s-1CPAN\s0.pm works nicely without network access, too. If you maintain machines that are not networked at all, you should consider working with \f(CW\*(C`file:\*(C'\fR URLs. You'll have to collect your modules somewhere first. So you might use \s-1CPAN\s0.pm to put together all you need on a networked machine. Then copy the \f(CW$CPAN::Config\fR\->{keep_source_where} (but not \&\f(CW$CPAN::Config\fR\->{build_dir}) directory on a floppy. This floppy is kind of a personal \s-1CPAN. CPAN\s0.pm on the non-networked machines works nicely with this floppy. See also below the paragraph about CD-ROM support. .SS "Basic Utilities for Programmers" .IX Subsection "Basic Utilities for Programmers" .IP "has_inst($module)" 2 .IX Item "has_inst($module)" Returns true if the module is installed. Used to load all modules into the running \s-1CPAN\s0.pm that are considered optional. The config variable \&\f(CW\*(C`dontload_list\*(C'\fR intercepts the \f(CW\*(C`has_inst()\*(C'\fR call such that an optional module is not loaded despite being available. For example, the following command will prevent \f(CW\*(C`YAML.pm\*(C'\fR from being loaded: .Sp .Vb 1 \& cpan> o conf dontload_list push YAML .Ve .Sp See the source for details. .IP "use_inst($module)" 2 .IX Item "use_inst($module)" Similary to \fBhas_inst()\fR tries to load optional library but also dies if library is not available .IP "has_usable($module)" 2 .IX Item "has_usable($module)" Returns true if the module is installed and in a usable state. Only useful for a handful of modules that are used internally. See the source for details. .IP "instance($module)" 2 .IX Item "instance($module)" The constructor for all the singletons used to represent modules, distributions, authors, and bundles. If the object already exists, this method returns the object; otherwise, it calls the constructor. .IP "\fBfrontend()\fR" 2 .IX Item "frontend()" .PD 0 .IP "frontend($new_frontend)" 2 .IX Item "frontend($new_frontend)" .PD Getter/setter for frontend object. Method just allows to subclass \s-1CPAN\s0.pm. .SH "SECURITY" .IX Header "SECURITY" There's no strong security layer in \s-1CPAN\s0.pm. \s-1CPAN\s0.pm helps you to install foreign, unmasked, unsigned code on your machine. We compare to a checksum that comes from the net just as the distribution file itself. But we try to make it easy to add security on demand: .SS "Cryptographically signed modules" .IX Subsection "Cryptographically signed modules" Since release 1.77, \s-1CPAN\s0.pm has been able to verify cryptographically signed module distributions using Module::Signature. The \s-1CPAN\s0 modules can be signed by their authors, thus giving more security. The simple unsigned \s-1MD5\s0 checksums that were used before by \s-1CPAN\s0 protect mainly against accidental file corruption. .PP You will need to have Module::Signature installed, which in turn requires that you have at least one of Crypt::OpenPGP module or the command-line \fIgpg\fR tool installed. .PP You will also need to be able to connect over the Internet to the public key servers, like pgp.mit.edu, and their port 11731 (the \s-1HKP\s0 protocol). .PP The configuration parameter check_sigs is there to turn signature checking on or off. .SH "EXPORT" .IX Header "EXPORT" Most functions in package \s-1CPAN\s0 are exported by default. The reason for this is that the primary use is intended for the cpan shell or for one-liners. .SH "ENVIRONMENT" .IX Header "ENVIRONMENT" When the \s-1CPAN\s0 shell enters a subshell via the look command, it sets the environment \s-1CPAN_SHELL_LEVEL\s0 to 1, or increments that variable if it is already set. .PP When \s-1CPAN\s0 runs, it sets the environment variable \s-1PERL5_CPAN_IS_RUNNING\s0 to the \s-1ID\s0 of the running process. It also sets \&\s-1PERL5_CPANPLUS_IS_RUNNING\s0 to prevent runaway processes which could happen with older versions of Module::Install. .PP When running \f(CW\*(C`perl Makefile.PL\*(C'\fR, the environment variable \&\f(CW\*(C`PERL5_CPAN_IS_EXECUTING\*(C'\fR is set to the full path of the \&\f(CW\*(C`Makefile.PL\*(C'\fR that is being executed. This prevents runaway processes with newer versions of Module::Install. .PP When the config variable ftp_passive is set, all downloads will be run with the environment variable \s-1FTP_PASSIVE\s0 set to this value. This is in general a good idea as it influences both Net::FTP and \s-1LWP\s0 based connections. The same effect can be achieved by starting the cpan shell with this environment variable set. For Net::FTP alone, one can also always set passive mode by running libnetcfg. .SH "POPULATE AN INSTALLATION WITH LOTS OF MODULES" .IX Header "POPULATE AN INSTALLATION WITH LOTS OF MODULES" Populating a freshly installed perl with one's favorite modules is pretty easy if you maintain a private bundle definition file. To get a useful blueprint of a bundle definition file, the command autobundle can be used on the \s-1CPAN\s0 shell command line. This command writes a bundle definition file for all modules installed for the current perl interpreter. It's recommended to run this command once only, and from then on maintain the file manually under a private name, say Bundle/my_bundle.pm. With a clever bundle file you can then simply say .PP .Vb 1 \& cpan> install Bundle::my_bundle .Ve .PP then answer a few questions and go out for coffee (possibly even in a different city). .PP Maintaining a bundle definition file means keeping track of two things: dependencies and interactivity. \s-1CPAN\s0.pm sometimes fails on calculating dependencies because not all modules define all MakeMaker attributes correctly, so a bundle definition file should specify prerequisites as early as possible. On the other hand, it's annoying that so many distributions need some interactive configuring. So what you can try to accomplish in your private bundle file is to have the packages that need to be configured early in the file and the gentle ones later, so you can go out for coffee after a few minutes and leave \s-1CPAN\s0.pm to churn away unattended. .SH "WORKING WITH CPAN.pm BEHIND FIREWALLS" .IX Header "WORKING WITH CPAN.pm BEHIND FIREWALLS" Thanks to Graham Barr for contributing the following paragraphs about the interaction between perl, and various firewall configurations. For further information on firewalls, it is recommended to consult the documentation that comes with the \fIncftp\fR program. If you are unable to go through the firewall with a simple Perl setup, it is likely that you can configure \fIncftp\fR so that it works through your firewall. .SS "Three basic types of firewalls" .IX Subsection "Three basic types of firewalls" Firewalls can be categorized into three basic types. .IP "http firewall" 4 .IX Item "http firewall" This is when the firewall machine runs a web server, and to access the outside world, you must do so via that web server. If you set environment variables like http_proxy or ftp_proxy to values beginning with http://, or in your web browser you've proxy information set, then you know you are running behind an http firewall. .Sp To access servers outside these types of firewalls with perl (even for ftp), you need \s-1LWP\s0 or HTTP::Tiny. .IP "ftp firewall" 4 .IX Item "ftp firewall" This where the firewall machine runs an ftp server. This kind of firewall will only let you access ftp servers outside the firewall. This is usually done by connecting to the firewall with ftp, then entering a username like \*(L"user@outside.host.com\*(R". .Sp To access servers outside these type of firewalls with perl, you need Net::FTP. .IP "One-way visibility" 4 .IX Item "One-way visibility" One-way visibility means these firewalls try to make themselves invisible to users inside the firewall. An \s-1FTP\s0 data connection is normally created by sending your \s-1IP\s0 address to the remote server and then listening for the return connection. But the remote server will not be able to connect to you because of the firewall. For these types of firewall, \&\s-1FTP\s0 connections need to be done in a passive mode. .Sp There are two that I can think off. .RS 4 .IP "\s-1SOCKS\s0" 4 .IX Item "SOCKS" If you are using a \s-1SOCKS\s0 firewall, you will need to compile perl and link it with the \s-1SOCKS\s0 library. This is what is normally called a 'socksified' perl. With this executable you will be able to connect to servers outside the firewall as if it were not there. .IP "\s-1IP\s0 Masquerade" 4 .IX Item "IP Masquerade" This is when the firewall implemented in the kernel (via \s-1NAT,\s0 or networking address translation), it allows you to hide a complete network behind one \&\s-1IP\s0 address. With this firewall no special compiling is needed as you can access hosts directly. .Sp For accessing ftp servers behind such firewalls you usually need to set the environment variable \f(CW\*(C`FTP_PASSIVE\*(C'\fR or the config variable ftp_passive to a true value. .RE .RS 4 .RE .SS "Configuring lynx or ncftp for going through a firewall" .IX Subsection "Configuring lynx or ncftp for going through a firewall" If you can go through your firewall with e.g. lynx, presumably with a command such as .PP .Vb 1 \& /usr/local/bin/lynx \-pscott:tiger .Ve .PP then you would configure \s-1CPAN\s0.pm with the command .PP .Vb 1 \& o conf lynx "/usr/local/bin/lynx \-pscott:tiger" .Ve .PP That's all. Similarly for ncftp or ftp, you would configure something like .PP .Vb 1 \& o conf ncftp "/usr/bin/ncftp \-f /home/scott/ncftplogin.cfg" .Ve .PP Your mileage may vary... .SH "FAQ" .IX Header "FAQ" .IP "1)" 4 .IX Item "1)" I installed a new version of module X but \s-1CPAN\s0 keeps saying, I have the old version installed .Sp Probably you \fBdo\fR have the old version installed. This can happen if a module installs itself into a different directory in the \&\f(CW@INC\fR path than it was previously installed. This is not really a \&\s-1CPAN\s0.pm problem, you would have the same problem when installing the module manually. The easiest way to prevent this behaviour is to add the argument \f(CW\*(C`UNINST=1\*(C'\fR to the \f(CW\*(C`make install\*(C'\fR call, and that is why many people add this argument permanently by configuring .Sp .Vb 1 \& o conf make_install_arg UNINST=1 .Ve .IP "2)" 4 .IX Item "2)" So why is UNINST=1 not the default? .Sp Because there are people who have their precise expectations about who may install where in the \f(CW@INC\fR path and who uses which \f(CW@INC\fR array. In fine tuned environments \f(CW\*(C`UNINST=1\*(C'\fR can cause damage. .IP "3)" 4 .IX Item "3)" I want to clean up my mess, and install a new perl along with all modules I have. How do I go about it? .Sp Run the autobundle command for your old perl and optionally rename the resulting bundle file (e.g. Bundle/mybundle.pm), install the new perl with the Configure option prefix, e.g. .Sp .Vb 1 \& ./Configure \-Dprefix=/usr/local/perl\-5.6.78.9 .Ve .Sp Install the bundle file you produced in the first step with something like .Sp .Vb 1 \& cpan> install Bundle::mybundle .Ve .Sp and you're done. .IP "4)" 4 .IX Item "4)" When I install bundles or multiple modules with one command there is too much output to keep track of. .Sp You may want to configure something like .Sp .Vb 2 \& o conf make_arg "| tee \-ai /root/.cpan/logs/make.out" \& o conf make_install_arg "| tee \-ai /root/.cpan/logs/make_install.out" .Ve .Sp so that \s-1STDOUT\s0 is captured in a file for later inspection. .IP "5)" 4 .IX Item "5)" I am not root, how can I install a module in a personal directory? .Sp As of \s-1CPAN 1.9463,\s0 if you do not have permission to write the default perl library directories, \s-1CPAN\s0's configuration process will ask you whether you want to bootstrap , which makes keeping a personal perl library directory easy. .Sp Another thing you should bear in mind is that the \s-1UNINST\s0 parameter can be dangerous when you are installing into a private area because you might accidentally remove modules that other people depend on that are not using the private area. .IP "6)" 4 .IX Item "6)" How to get a package, unwrap it, and make a change before building it? .Sp Have a look at the \f(CW\*(C`look\*(C'\fR (!) command. .IP "7)" 4 .IX Item "7)" I installed a Bundle and had a couple of fails. When I retried, everything resolved nicely. Can this be fixed to work on first try? .Sp The reason for this is that \s-1CPAN\s0 does not know the dependencies of all modules when it starts out. To decide about the additional items to install, it just uses data found in the \s-1META\s0.yml file or the generated Makefile. An undetected missing piece breaks the process. But it may well be that your Bundle installs some prerequisite later than some depending item and thus your second try is able to resolve everything. Please note, \s-1CPAN\s0.pm does not know the dependency tree in advance and cannot sort the queue of things to install in a topologically correct order. It resolves perfectly well \fBif\fR all modules declare the prerequisites correctly with the \s-1PREREQ_PM\s0 attribute to MakeMaker or the \f(CW\*(C`requires\*(C'\fR stanza of Module::Build. For bundles which fail and you need to install often, it is recommended to sort the Bundle definition file manually. .IP "8)" 4 .IX Item "8)" In our intranet, we have many modules for internal use. How can I integrate these modules with \s-1CPAN\s0.pm but without uploading the modules to \s-1CPAN\s0? .Sp Have a look at the CPAN::Site module. .IP "9)" 4 .IX Item "9)" When I run \s-1CPAN\s0's shell, I get an error message about things in my \&\f(CW\*(C`/etc/inputrc\*(C'\fR (or \f(CW\*(C`~/.inputrc\*(C'\fR) file. .Sp These are readline issues and can only be fixed by studying readline configuration on your architecture and adjusting the referenced file accordingly. Please make a backup of the \f(CW\*(C`/etc/inputrc\*(C'\fR or \f(CW\*(C`~/.inputrc\*(C'\fR and edit them. Quite often harmless changes like uppercasing or lowercasing some arguments solves the problem. .IP "10)" 4 .IX Item "10)" Some authors have strange characters in their names. .Sp Internally \s-1CPAN\s0.pm uses the \s-1UTF\-8\s0 charset. If your terminal is expecting \s-1ISO\-8859\-1\s0 charset, a converter can be activated by setting term_is_latin to a true value in your config file. One way of doing so would be .Sp .Vb 1 \& cpan> o conf term_is_latin 1 .Ve .Sp If other charset support is needed, please file a bug report against \&\s-1CPAN\s0.pm at rt.cpan.org and describe your needs. Maybe we can extend the support or maybe \s-1UTF\-8\s0 terminals become widely available. .Sp Note: this config variable is deprecated and will be removed in a future version of \s-1CPAN\s0.pm. It will be replaced with the conventions around the family of \f(CW$LANG\fR and \f(CW$LC_\fR* environment variables. .IP "11)" 4 .IX Item "11)" When an install fails for some reason and then I correct the error condition and retry, \s-1CPAN\s0.pm refuses to install the module, saying \&\f(CW\*(C`Already tried without success\*(C'\fR. .Sp Use the force pragma like so .Sp .Vb 1 \& force install Foo::Bar .Ve .Sp Or you can use .Sp .Vb 1 \& look Foo::Bar .Ve .Sp and then \f(CW\*(C`make install\*(C'\fR directly in the subshell. .IP "12)" 4 .IX Item "12)" How do I install a \*(L"\s-1DEVELOPER RELEASE\*(R"\s0 of a module? .Sp By default, \s-1CPAN\s0 will install the latest non-developer release of a module. If you want to install a dev release, you have to specify the partial path starting with the author id to the tarball you wish to install, like so: .Sp .Vb 1 \& cpan> install KWILLIAMS/Module\-Build\-0.27_07.tar.gz .Ve .Sp Note that you can use the \f(CW\*(C`ls\*(C'\fR command to get this path listed. .IP "13)" 4 .IX Item "13)" How do I install a module and all its dependencies from the commandline, without being prompted for anything, despite my \s-1CPAN\s0 configuration (or lack thereof)? .Sp \&\s-1CPAN\s0 uses ExtUtils::MakeMaker's \fBprompt()\fR function to ask its questions, so if you set the \s-1PERL_MM_USE_DEFAULT\s0 environment variable, you shouldn't be asked any questions at all (assuming the modules you are installing are nice about obeying that variable as well): .Sp .Vb 1 \& % PERL_MM_USE_DEFAULT=1 perl \-MCPAN \-e \*(Aqinstall My::Module\*(Aq .Ve .IP "14)" 4 .IX Item "14)" How do I create a Module::Build based Build.PL derived from an ExtUtils::MakeMaker focused Makefile.PL? .Sp http://search.cpan.org/dist/Module\-Build\-Convert/ .IP "15)" 4 .IX Item "15)" I'm frequently irritated with the \s-1CPAN\s0 shell's inability to help me select a good mirror. .Sp \&\s-1CPAN\s0 can now help you select a \*(L"good\*(R" mirror, based on which ones have the lowest 'ping' round-trip times. From the shell, use the command 'o conf init urllist' and allow \s-1CPAN\s0 to automatically select mirrors for you. .Sp Beyond that help, the urllist config parameter is yours. You can add and remove sites at will. You should find out which sites have the best up-to-dateness, bandwidth, reliability, etc. and are topologically close to you. Some people prefer fast downloads, others up-to-dateness, others reliability. You decide which to try in which order. .Sp Henk P. Penning maintains a site that collects data about \s-1CPAN\s0 sites: .Sp .Vb 1 \& http://mirrors.cpan.org/ .Ve .Sp Also, feel free to play with experimental features. Run .Sp .Vb 1 \& o conf init randomize_urllist ftpstats_period ftpstats_size .Ve .Sp and choose your favorite parameters. After a few downloads running the \&\f(CW\*(C`hosts\*(C'\fR command will probably assist you in choosing the best mirror sites. .IP "16)" 4 .IX Item "16)" Why do I get asked the same questions every time I start the shell? .Sp You can make your configuration changes permanent by calling the command \f(CW\*(C`o conf commit\*(C'\fR. Alternatively set the \f(CW\*(C`auto_commit\*(C'\fR variable to true by running \f(CW\*(C`o conf init auto_commit\*(C'\fR and answering the following question with yes. .IP "17)" 4 .IX Item "17)" Older versions of \s-1CPAN\s0.pm had the original root directory of all tarballs in the build directory. Now there are always random characters appended to these directory names. Why was this done? .Sp The random characters are provided by File::Temp and ensure that each module's individual build directory is unique. This makes running \&\s-1CPAN\s0.pm in concurrent processes simultaneously safe. .IP "18)" 4 .IX Item "18)" Speaking of the build directory. Do I have to clean it up myself? .Sp You have the choice to set the config variable \f(CW\*(C`scan_cache\*(C'\fR to \&\f(CW\*(C`never\*(C'\fR. Then you must clean it up yourself. The other possible values, \f(CW\*(C`atstart\*(C'\fR and \f(CW\*(C`atexit\*(C'\fR clean up the build directory when you start (or more precisely, after the first extraction into the build directory) or exit the \s-1CPAN\s0 shell, respectively. If you never start up the \s-1CPAN\s0 shell, you probably also have to clean up the build directory yourself. .IP "19)" 4 .IX Item "19)" How can I switch to sudo instead of local::lib? .Sp The following 5 environment veriables need to be reset to the previous values: \s-1PATH, PERL5LIB, PERL_LOCAL_LIB_ROOT, PERL_MB_OPT, PERL_MM_OPT\s0; and these two \s-1CPAN\s0.pm config variables must be reconfigured: make_install_make_command and mbuild_install_build_command. The five env variables have probably been overwritten in your \f(CW$HOME\fR/.bashrc or some equivalent. You either find them there and delete their traces and logout/login or you override them temporarily, depending on your exact desire. The two cpanpm config variables can be set with: .Sp .Vb 1 \& o conf init /install_.*_command/ .Ve .Sp probably followed by .Sp .Vb 1 \& o conf commit .Ve .SH "COMPATIBILITY" .IX Header "COMPATIBILITY" .SS "\s-1OLD PERL VERSIONS\s0" .IX Subsection "OLD PERL VERSIONS" \&\s-1CPAN\s0.pm is regularly tested to run under 5.005 and assorted newer versions. It is getting more and more difficult to get the minimal prerequisites working on older perls. It is close to impossible to get the whole Bundle::CPAN working there. If you're in the position to have only these old versions, be advised that \s-1CPAN\s0 is designed to work fine without the Bundle::CPAN installed. .PP To get things going, note that GBARR/Scalar\-List\-Utils\-1.18.tar.gz is compatible with ancient perls and that File::Temp is listed as a prerequisite but \s-1CPAN\s0 has reasonable workarounds if it is missing. .SS "\s-1CPANPLUS\s0" .IX Subsection "CPANPLUS" This module and its competitor, the \s-1CPANPLUS\s0 module, are both much cooler than the other. \s-1CPAN\s0.pm is older. \s-1CPANPLUS\s0 was designed to be more modular, but it was never intended to be compatible with \s-1CPAN\s0.pm. .SS "\s-1CPANMINUS\s0" .IX Subsection "CPANMINUS" In the year 2010 App::cpanminus was launched as a new approach to a cpan shell with a considerably smaller footprint. Very cool stuff. .SH "SECURITY ADVICE" .IX Header "SECURITY ADVICE" This software enables you to upgrade software on your computer and so is inherently dangerous because the newly installed software may contain bugs and may alter the way your computer works or even make it unusable. Please consider backing up your data before every upgrade. .SH "BUGS" .IX Header "BUGS" Please report bugs via .PP Before submitting a bug, please make sure that the traditional method of building a Perl module package from a shell by following the installation instructions of that package still works in your environment. .SH "AUTHOR" .IX Header "AUTHOR" Andreas Koenig \f(CW\*(C`\*(C'\fR .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP See .SH "TRANSLATIONS" .IX Header "TRANSLATIONS" Kawai,Takanori provides a Japanese translation of a very old version of this manpage at .SH "SEE ALSO" .IX Header "SEE ALSO" Many people enter the \s-1CPAN\s0 shell by running the cpan utility program which is installed in the same directory as perl itself. So if you have this directory in your \s-1PATH\s0 variable (or some equivalent in your operating system) then typing \f(CW\*(C`cpan\*(C'\fR in a console window will work for you as well. Above that the utility provides several commandline shortcuts. .PP melezhik (Alexey) sent me a link where he published a chef recipe to work with \s-1CPAN\s0.pm: http://community.opscode.com/cookbooks/cpan. PK@O\WJSON::Syck.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "JSON::Syck 3" .TH JSON::Syck 3 "2020-10-26" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" JSON::Syck \- JSON is YAML (but consider using JSON::XS instead!) .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use JSON::Syck; # no exports by default \& \& my $data = JSON::Syck::Load($json); \& my $json = JSON::Syck::Dump($data); \& \& # $file can be an IO object, or a filename \& my $data = JSON::Syck::LoadFile($file); \& JSON::Syck::DumpFile($file, $data); \& \& # Dump into a pre\-existing buffer \& my $json; \& JSON::Syck::DumpInto(\e$json, $data); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" JSON::Syck is a syck implementation of \s-1JSON\s0 parsing and generation. Because \&\s-1JSON\s0 is \s-1YAML\s0 (), using syck gives you a fast and memory-efficient parser and dumper for \s-1JSON\s0 data representation. .PP However, a newer module \s-1JSON::XS\s0, has since emerged. It is more flexible, efficient and robust, so please consider using it instead of this module. .SH "DIFFERENCE WITH JSON" .IX Header "DIFFERENCE WITH JSON" You might want to know the difference between the \fI\s-1JSON\s0\fR module and this one. .PP Since \s-1JSON\s0 is a pure-perl module and JSON::Syck is based on libsyck, JSON::Syck is supposed to be very fast and memory efficient. See chansen's benchmark table at .PP \&\s-1JSON\s0.pm comes with dozens of ways to do the same thing and lots of options, while JSON::Syck doesn't. There's only \f(CW\*(C`Load\*(C'\fR and \f(CW\*(C`Dump\*(C'\fR. .PP Oh, and JSON::Syck doesn't use camelCase method names :\-) .SH "REFERENCES" .IX Header "REFERENCES" .SS "\s-1SCALAR REFERENCE\s0" .IX Subsection "SCALAR REFERENCE" For now, when you pass a scalar reference to JSON::Syck, it dereferences to get the actual scalar value. .PP JSON::Syck raises an exception when you pass in circular references. .PP If you want to serialize self referencing stuff, you should use \&\s-1YAML\s0 which supports it. .SS "\s-1SUBROUTINE REFERENCE\s0" .IX Subsection "SUBROUTINE REFERENCE" When you pass subroutine reference, JSON::Syck dumps it as null. .SH "UTF\-8 FLAGS" .IX Header "UTF-8 FLAGS" By default this module doesn't touch any of utf\-8 flags set in strings, and assumes \s-1UTF\-8\s0 bytes to be passed and emit. .PP However, when you set \f(CW$JSON::Syck::ImplicitUnicode\fR to 1, this module properly decodes \s-1UTF\-8\s0 binaries and sets \s-1UTF\-8\s0 flag everywhere, as in: .PP .Vb 4 \& JSON (UTF\-8 bytes) => Perl (UTF\-8 flagged) \& JSON (UTF\-8 flagged) => Perl (UTF\-8 flagged) \& Perl (UTF\-8 bytes) => JSON (UTF\-8 flagged) \& Perl (UTF\-8 flagged) => JSON (UTF\-8 flagged) .Ve .PP By default, JSON::Syck::Dump will only transverse up to 512 levels of a datastructure in order to avoid an infinite loop when it is presented with an circular reference. .PP However, you set \f(CW$JSON::Syck::MaxLevels\fR to a larger value if you have very complex structures. .PP Unfortunately, there's no implicit way to dump Perl \s-1UTF\-8\s0 flagged data structure to utf\-8 encoded \s-1JSON.\s0 To do this, simply use Encode module, e.g.: .PP .Vb 2 \& use Encode; \& use JSON::Syck qw(Dump); \& \& my $json = encode_utf8( Dump($data) ); .Ve .PP Alternatively you can use Encode::JavaScript::UCS to encode Unicode strings as in \fI\f(CI%uXXXX\fI\fR form. .PP .Vb 3 \& use Encode; \& use Encode::JavaScript::UCS; \& use JSON::Syck qw(Dump); \& \& my $json_unicode_escaped = encode( \*(AqJavaScript\-UCS\*(Aq, Dump($data) ); .Ve .SH "QUOTING" .IX Header "QUOTING" According to the \s-1JSON\s0 specification, all \s-1JSON\s0 strings are to be double-quoted. However, when embedding JavaScript in \s-1HTML\s0 attributes, it may be more convenient to use single quotes. .PP Set \f(CW$JSON::Syck::SingleQuote\fR to 1 will make both \f(CW\*(C`Dump\*(C'\fR and \f(CW\*(C`Load\*(C'\fR expect single-quoted string literals. .SH "BUGS" .IX Header "BUGS" Dumping into tied (or other magic variables) with \f(CW\*(C`DumpInto\*(C'\fR might not work properly in all cases. .PP When dumping with \f(CW\*(C`DumpFile\*(C'\fR, some spacing might be wrong and \&\f(CW$JSON::Syck::SingleQuote\fR might be handled incorrectly. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1JSON::XS\s0, YAML::Syck .SH "AUTHORS" .IX Header "AUTHORS" Audrey Tang .PP Tatsuhiko Miyagawa .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2005\-2009 by Audrey Tang . .PP This software is released under the \s-1MIT\s0 license cited below. .PP The \fIlibsyck\fR code bundled with this library is released by \&\*(L"why the lucky stiff\*(R", under a BSD-style license. See the \fI\s-1COPYING\s0\fR file for details. .ie n .SS "The ""\s-1MIT""\s0 License" .el .SS "The ``\s-1MIT''\s0 License" .IX Subsection "The MIT License" Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \*(L"Software\*(R"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: .PP The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. .PP \&\s-1THE SOFTWARE IS PROVIDED \*(L"AS IS\*(R", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\s0 PK@O\qo[[ JSON::XS.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "XS 3" .TH XS 3 "2020-10-27" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" JSON::XS \- JSON serialising/deserialising, done correctly and fast .PP JSON::XS \- 正しくて高速な JSON シリアライザ/デシリアライザ (http://fleur.hio.jp/perldoc/mix/lib/JSON/XS.html) .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use JSON::XS; \& \& # exported functions, they croak on error \& # and expect/generate UTF\-8 \& \& $utf8_encoded_json_text = encode_json $perl_hash_or_arrayref; \& $perl_hash_or_arrayref = decode_json $utf8_encoded_json_text; \& \& # OO\-interface \& \& $coder = JSON::XS\->new\->ascii\->pretty\->allow_nonref; \& $pretty_printed_unencoded = $coder\->encode ($perl_scalar); \& $perl_scalar = $coder\->decode ($unicode_json_text); \& \& # Note that JSON version 2.0 and above will automatically use JSON::XS \& # if available, at virtually no speed overhead either, so you should \& # be able to just: \& \& use JSON; \& \& # and do the same things, except that you have a pure\-perl fallback now. .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module converts Perl data structures to \s-1JSON\s0 and vice versa. Its primary goal is to be \fIcorrect\fR and its secondary goal is to be \&\fIfast\fR. To reach the latter goal it was written in C. .PP See \s-1MAPPING,\s0 below, on how \s-1JSON::XS\s0 maps perl values to \s-1JSON\s0 values and vice versa. .SS "\s-1FEATURES\s0" .IX Subsection "FEATURES" .IP "\(bu" 4 correct Unicode handling .Sp This module knows how to handle Unicode, documents how and when it does so, and even documents what \*(L"correct\*(R" means. .IP "\(bu" 4 round-trip integrity .Sp When you serialise a perl data structure using only data types supported by \s-1JSON\s0 and Perl, the deserialised data structure is identical on the Perl level. (e.g. the string \*(L"2.0\*(R" doesn't suddenly become \*(L"2\*(R" just because it looks like a number). There \fIare\fR minor exceptions to this, read the \&\s-1MAPPING\s0 section below to learn about those. .IP "\(bu" 4 strict checking of \s-1JSON\s0 correctness .Sp There is no guessing, no generating of illegal \s-1JSON\s0 texts by default, and only \s-1JSON\s0 is accepted as input by default (the latter is a security feature). .IP "\(bu" 4 fast .Sp Compared to other \s-1JSON\s0 modules and other serialisers such as Storable, this module usually compares favourably in terms of speed, too. .IP "\(bu" 4 simple to use .Sp This module has both a simple functional interface as well as an object oriented interface. .IP "\(bu" 4 reasonably versatile output formats .Sp You can choose between the most compact guaranteed-single-line format possible (nice for simple line-based protocols), a pure-ASCII format (for when your transport is not 8\-bit clean, still supports the whole Unicode range), or a pretty-printed format (for when you want to read that stuff). Or you can combine those features in whatever way you like. .SH "FUNCTIONAL INTERFACE" .IX Header "FUNCTIONAL INTERFACE" The following convenience methods are provided by this module. They are exported by default: .ie n .IP "$json_text = encode_json $perl_scalar" 4 .el .IP "\f(CW$json_text\fR = encode_json \f(CW$perl_scalar\fR" 4 .IX Item "$json_text = encode_json $perl_scalar" Converts the given Perl data structure to a \s-1UTF\-8\s0 encoded, binary string (that is, the string contains octets only). Croaks on error. .Sp This function call is functionally identical to: .Sp .Vb 1 \& $json_text = JSON::XS\->new\->utf8\->encode ($perl_scalar) .Ve .Sp Except being faster. .ie n .IP "$perl_scalar = decode_json $json_text" 4 .el .IP "\f(CW$perl_scalar\fR = decode_json \f(CW$json_text\fR" 4 .IX Item "$perl_scalar = decode_json $json_text" The opposite of \f(CW\*(C`encode_json\*(C'\fR: expects a \s-1UTF\-8\s0 (binary) string and tries to parse that as a \s-1UTF\-8\s0 encoded \s-1JSON\s0 text, returning the resulting reference. Croaks on error. .Sp This function call is functionally identical to: .Sp .Vb 1 \& $perl_scalar = JSON::XS\->new\->utf8\->decode ($json_text) .Ve .Sp Except being faster. .SH "A FEW NOTES ON UNICODE AND PERL" .IX Header "A FEW NOTES ON UNICODE AND PERL" Since this often leads to confusion, here are a few very clear words on how Unicode works in Perl, modulo bugs. .IP "1. Perl strings can store characters with ordinal values > 255." 4 .IX Item "1. Perl strings can store characters with ordinal values > 255." This enables you to store Unicode characters as single characters in a Perl string \- very natural. .IP "2. Perl does \fInot\fR associate an encoding with your strings." 4 .IX Item "2. Perl does not associate an encoding with your strings." \&... until you force it to, e.g. when matching it against a regex, or printing the scalar to a file, in which case Perl either interprets your string as locale-encoded text, octets/binary, or as Unicode, depending on various settings. In no case is an encoding stored together with your data, it is \fIuse\fR that decides encoding, not any magical meta data. .IP "3. The internal utf\-8 flag has no meaning with regards to the encoding of your string." 4 .IX Item "3. The internal utf-8 flag has no meaning with regards to the encoding of your string." Just ignore that flag unless you debug a Perl bug, a module written in \&\s-1XS\s0 or want to dive into the internals of perl. Otherwise it will only confuse you, as, despite the name, it says nothing about how your string is encoded. You can have Unicode strings with that flag set, with that flag clear, and you can have binary data with that flag set and that flag clear. Other possibilities exist, too. .Sp If you didn't know about that flag, just the better, pretend it doesn't exist. .ie n .IP "4. A ""Unicode String"" is simply a string where each character can be validly interpreted as a Unicode code point." 4 .el .IP "4. A ``Unicode String'' is simply a string where each character can be validly interpreted as a Unicode code point." 4 .IX Item "4. A Unicode String is simply a string where each character can be validly interpreted as a Unicode code point." If you have \s-1UTF\-8\s0 encoded data, it is no longer a Unicode string, but a Unicode string encoded in \s-1UTF\-8,\s0 giving you a binary string. .ie n .IP "5. A string containing ""high"" (> 255) character values is \fInot\fR a \s-1UTF\-8\s0 string." 4 .el .IP "5. A string containing ``high'' (> 255) character values is \fInot\fR a \s-1UTF\-8\s0 string." 4 .IX Item "5. A string containing high (> 255) character values is not a UTF-8 string." It's a fact. Learn to live with it. .PP I hope this helps :) .SH "OBJECT-ORIENTED INTERFACE" .IX Header "OBJECT-ORIENTED INTERFACE" The object oriented interface lets you configure your own encoding or decoding style, within the limits of supported formats. .ie n .IP "$json = new \s-1JSON::XS\s0" 4 .el .IP "\f(CW$json\fR = new \s-1JSON::XS\s0" 4 .IX Item "$json = new JSON::XS" Creates a new \s-1JSON::XS\s0 object that can be used to de/encode \s-1JSON\s0 strings. All boolean flags described below are by default \fIdisabled\fR (with the exception of \f(CW\*(C`allow_nonref\*(C'\fR, which defaults to \fIenabled\fR since version \f(CW4.0\fR). .Sp The mutators for flags all return the \s-1JSON\s0 object again and thus calls can be chained: .Sp .Vb 2 \& my $json = JSON::XS\->new\->utf8\->space_after\->encode ({a => [1,2]}) \& => {"a": [1, 2]} .Ve .ie n .IP "$json = $json\->ascii ([$enable])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->ascii ([$enable])" 4 .IX Item "$json = $json->ascii ([$enable])" .PD 0 .ie n .IP "$enabled = $json\->get_ascii" 4 .el .IP "\f(CW$enabled\fR = \f(CW$json\fR\->get_ascii" 4 .IX Item "$enabled = $json->get_ascii" .PD If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will not generate characters outside the code range \f(CW0..127\fR (which is \s-1ASCII\s0). Any Unicode characters outside that range will be escaped using either a single \euXXXX (\s-1BMP\s0 characters) or a double \euHHHH\euLLLLL escape sequence, as per \s-1RFC4627.\s0 The resulting encoded \s-1JSON\s0 text can be treated as a native Unicode string, an ascii-encoded, latin1\-encoded or \s-1UTF\-8\s0 encoded string, or any other superset of \s-1ASCII.\s0 .Sp If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not escape Unicode characters unless required by the \s-1JSON\s0 syntax or other flags. This results in a faster and more compact format. .Sp See also the section \fI\s-1ENCODING/CODESET FLAG NOTES\s0\fR later in this document. .Sp The main use for this flag is to produce \s-1JSON\s0 texts that can be transmitted over a 7\-bit channel, as the encoded \s-1JSON\s0 texts will not contain any 8 bit characters. .Sp .Vb 2 \& JSON::XS\->new\->ascii (1)\->encode ([chr 0x10401]) \& => ["\eud801\eudc01"] .Ve .ie n .IP "$json = $json\->latin1 ([$enable])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->latin1 ([$enable])" 4 .IX Item "$json = $json->latin1 ([$enable])" .PD 0 .ie n .IP "$enabled = $json\->get_latin1" 4 .el .IP "\f(CW$enabled\fR = \f(CW$json\fR\->get_latin1" 4 .IX Item "$enabled = $json->get_latin1" .PD If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will encode the resulting \s-1JSON\s0 text as latin1 (or iso\-8859\-1), escaping any characters outside the code range \f(CW0..255\fR. The resulting string can be treated as a latin1\-encoded \s-1JSON\s0 text or a native Unicode string. The \f(CW\*(C`decode\*(C'\fR method will not be affected in any way by this flag, as \f(CW\*(C`decode\*(C'\fR by default expects Unicode, which is a strict superset of latin1. .Sp If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not escape Unicode characters unless required by the \s-1JSON\s0 syntax or other flags. .Sp See also the section \fI\s-1ENCODING/CODESET FLAG NOTES\s0\fR later in this document. .Sp The main use for this flag is efficiently encoding binary data as \s-1JSON\s0 text, as most octets will not be escaped, resulting in a smaller encoded size. The disadvantage is that the resulting \s-1JSON\s0 text is encoded in latin1 (and must correctly be treated as such when storing and transferring), a rare encoding for \s-1JSON.\s0 It is therefore most useful when you want to store data structures known to contain binary data efficiently in files or databases, not when talking to other \s-1JSON\s0 encoders/decoders. .Sp .Vb 2 \& JSON::XS\->new\->latin1\->encode (["\ex{89}\ex{abc}"] \& => ["\ex{89}\e\eu0abc"] # (perl syntax, U+abc escaped, U+89 not) .Ve .ie n .IP "$json = $json\->utf8 ([$enable])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->utf8 ([$enable])" 4 .IX Item "$json = $json->utf8 ([$enable])" .PD 0 .ie n .IP "$enabled = $json\->get_utf8" 4 .el .IP "\f(CW$enabled\fR = \f(CW$json\fR\->get_utf8" 4 .IX Item "$enabled = $json->get_utf8" .PD If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will encode the \s-1JSON\s0 result into \s-1UTF\-8,\s0 as required by many protocols, while the \&\f(CW\*(C`decode\*(C'\fR method expects to be handed a UTF\-8\-encoded string. Please note that UTF\-8\-encoded strings do not contain any characters outside the range \f(CW0..255\fR, they are thus useful for bytewise/binary I/O. In future versions, enabling this option might enable autodetection of the \s-1UTF\-16\s0 and \s-1UTF\-32\s0 encoding families, as described in \s-1RFC4627.\s0 .Sp If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will return the \s-1JSON\s0 string as a (non-encoded) Unicode string, while \f(CW\*(C`decode\*(C'\fR expects thus a Unicode string. Any decoding or encoding (e.g. to \s-1UTF\-8\s0 or \s-1UTF\-16\s0) needs to be done yourself, e.g. using the Encode module. .Sp See also the section \fI\s-1ENCODING/CODESET FLAG NOTES\s0\fR later in this document. .Sp Example, output UTF\-16BE\-encoded \s-1JSON:\s0 .Sp .Vb 2 \& use Encode; \& $jsontext = encode "UTF\-16BE", JSON::XS\->new\->encode ($object); .Ve .Sp Example, decode UTF\-32LE\-encoded \s-1JSON:\s0 .Sp .Vb 2 \& use Encode; \& $object = JSON::XS\->new\->decode (decode "UTF\-32LE", $jsontext); .Ve .ie n .IP "$json = $json\->pretty ([$enable])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->pretty ([$enable])" 4 .IX Item "$json = $json->pretty ([$enable])" This enables (or disables) all of the \f(CW\*(C`indent\*(C'\fR, \f(CW\*(C`space_before\*(C'\fR and \&\f(CW\*(C`space_after\*(C'\fR (and in the future possibly more) flags in one call to generate the most readable (or most compact) form possible. .Sp Example, pretty-print some simple structure: .Sp .Vb 8 \& my $json = JSON::XS\->new\->pretty(1)\->encode ({a => [1,2]}) \& => \& { \& "a" : [ \& 1, \& 2 \& ] \& } .Ve .ie n .IP "$json = $json\->indent ([$enable])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->indent ([$enable])" 4 .IX Item "$json = $json->indent ([$enable])" .PD 0 .ie n .IP "$enabled = $json\->get_indent" 4 .el .IP "\f(CW$enabled\fR = \f(CW$json\fR\->get_indent" 4 .IX Item "$enabled = $json->get_indent" .PD If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will use a multiline format as output, putting every array member or object/hash key-value pair into its own line, indenting them properly. .Sp If \f(CW$enable\fR is false, no newlines or indenting will be produced, and the resulting \s-1JSON\s0 text is guaranteed not to contain any \f(CW\*(C`newlines\*(C'\fR. .Sp This setting has no effect when decoding \s-1JSON\s0 texts. .ie n .IP "$json = $json\->space_before ([$enable])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->space_before ([$enable])" 4 .IX Item "$json = $json->space_before ([$enable])" .PD 0 .ie n .IP "$enabled = $json\->get_space_before" 4 .el .IP "\f(CW$enabled\fR = \f(CW$json\fR\->get_space_before" 4 .IX Item "$enabled = $json->get_space_before" .PD If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra optional space before the \f(CW\*(C`:\*(C'\fR separating keys from values in \s-1JSON\s0 objects. .Sp If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra space at those places. .Sp This setting has no effect when decoding \s-1JSON\s0 texts. You will also most likely combine this setting with \f(CW\*(C`space_after\*(C'\fR. .Sp Example, space_before enabled, space_after and indent disabled: .Sp .Vb 1 \& {"key" :"value"} .Ve .ie n .IP "$json = $json\->space_after ([$enable])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->space_after ([$enable])" 4 .IX Item "$json = $json->space_after ([$enable])" .PD 0 .ie n .IP "$enabled = $json\->get_space_after" 4 .el .IP "\f(CW$enabled\fR = \f(CW$json\fR\->get_space_after" 4 .IX Item "$enabled = $json->get_space_after" .PD If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will add an extra optional space after the \f(CW\*(C`:\*(C'\fR separating keys from values in \s-1JSON\s0 objects and extra whitespace after the \f(CW\*(C`,\*(C'\fR separating key-value pairs and array members. .Sp If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will not add any extra space at those places. .Sp This setting has no effect when decoding \s-1JSON\s0 texts. .Sp Example, space_before and indent disabled, space_after enabled: .Sp .Vb 1 \& {"key": "value"} .Ve .ie n .IP "$json = $json\->relaxed ([$enable])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->relaxed ([$enable])" 4 .IX Item "$json = $json->relaxed ([$enable])" .PD 0 .ie n .IP "$enabled = $json\->get_relaxed" 4 .el .IP "\f(CW$enabled\fR = \f(CW$json\fR\->get_relaxed" 4 .IX Item "$enabled = $json->get_relaxed" .PD If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`decode\*(C'\fR will accept some extensions to normal \s-1JSON\s0 syntax (see below). \f(CW\*(C`encode\*(C'\fR will not be affected in any way. \fIBe aware that this option makes you accept invalid \&\s-1JSON\s0 texts as if they were valid!\fR. I suggest only to use this option to parse application-specific files written by humans (configuration files, resource files etc.) .Sp If \f(CW$enable\fR is false (the default), then \f(CW\*(C`decode\*(C'\fR will only accept valid \s-1JSON\s0 texts. .Sp Currently accepted extensions are: .RS 4 .IP "\(bu" 4 list items can have an end-comma .Sp \&\s-1JSON\s0 \fIseparates\fR array elements and key-value pairs with commas. This can be annoying if you write \s-1JSON\s0 texts manually and want to be able to quickly append elements, so this extension accepts comma at the end of such items not just between them: .Sp .Vb 8 \& [ \& 1, \& 2, <\- this comma not normally allowed \& ] \& { \& "k1": "v1", \& "k2": "v2", <\- this comma not normally allowed \& } .Ve .IP "\(bu" 4 shell-style '#'\-comments .Sp Whenever \s-1JSON\s0 allows whitespace, shell-style comments are additionally allowed. They are terminated by the first carriage-return or line-feed character, after which more white-space and comments are allowed. .Sp .Vb 4 \& [ \& 1, # this comment not allowed in JSON \& # neither this one... \& ] .Ve .IP "\(bu" 4 literal \s-1ASCII TAB\s0 characters in strings .Sp Literal \s-1ASCII TAB\s0 characters are now allowed in strings (and treated as \&\f(CW\*(C`\et\*(C'\fR). .Sp .Vb 4 \& [ \& "Hello\etWorld", \& "HelloWorld", # literal would not normally be allowed \& ] .Ve .RE .RS 4 .RE .ie n .IP "$json = $json\->canonical ([$enable])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->canonical ([$enable])" 4 .IX Item "$json = $json->canonical ([$enable])" .PD 0 .ie n .IP "$enabled = $json\->get_canonical" 4 .el .IP "\f(CW$enabled\fR = \f(CW$json\fR\->get_canonical" 4 .IX Item "$enabled = $json->get_canonical" .PD If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will output \s-1JSON\s0 objects by sorting their keys. This is adding a comparatively high overhead. .Sp If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will output key-value pairs in the order Perl stores them (which will likely change between runs of the same script, and can change even within the same run from 5.18 onwards). .Sp This option is useful if you want the same data structure to be encoded as the same \s-1JSON\s0 text (given the same overall settings). If it is disabled, the same hash might be encoded differently even if contains the same data, as key-value pairs have no inherent ordering in Perl. .Sp This setting has no effect when decoding \s-1JSON\s0 texts. .Sp This setting has currently no effect on tied hashes. .ie n .IP "$json = $json\->allow_nonref ([$enable])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->allow_nonref ([$enable])" 4 .IX Item "$json = $json->allow_nonref ([$enable])" .PD 0 .ie n .IP "$enabled = $json\->get_allow_nonref" 4 .el .IP "\f(CW$enabled\fR = \f(CW$json\fR\->get_allow_nonref" 4 .IX Item "$enabled = $json->get_allow_nonref" .PD Unlike other boolean options, this opotion is enabled by default beginning with version \f(CW4.0\fR. See \*(L"\s-1SECURITY CONSIDERATIONS\*(R"\s0 for the gory details. .Sp If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method can convert a non-reference into its corresponding string, number or null \s-1JSON\s0 value, which is an extension to \s-1RFC4627.\s0 Likewise, \f(CW\*(C`decode\*(C'\fR will accept those \s-1JSON\s0 values instead of croaking. .Sp If \f(CW$enable\fR is false, then the \f(CW\*(C`encode\*(C'\fR method will croak if it isn't passed an arrayref or hashref, as \s-1JSON\s0 texts must either be an object or array. Likewise, \f(CW\*(C`decode\*(C'\fR will croak if given something that is not a \&\s-1JSON\s0 object or array. .Sp Example, encode a Perl scalar as \s-1JSON\s0 value without enabled \f(CW\*(C`allow_nonref\*(C'\fR, resulting in an error: .Sp .Vb 2 \& JSON::XS\->new\->allow_nonref (0)\->encode ("Hello, World!") \& => hash\- or arrayref expected... .Ve .ie n .IP "$json = $json\->allow_unknown ([$enable])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->allow_unknown ([$enable])" 4 .IX Item "$json = $json->allow_unknown ([$enable])" .PD 0 .ie n .IP "$enabled = $json\->get_allow_unknown" 4 .el .IP "\f(CW$enabled\fR = \f(CW$json\fR\->get_allow_unknown" 4 .IX Item "$enabled = $json->get_allow_unknown" .PD If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR will \fInot\fR throw an exception when it encounters values it cannot represent in \s-1JSON\s0 (for example, filehandles) but instead will encode a \s-1JSON\s0 \f(CW\*(C`null\*(C'\fR value. Note that blessed objects are not included here and are handled separately by c. .Sp If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will throw an exception when it encounters anything it cannot encode as \s-1JSON.\s0 .Sp This option does not affect \f(CW\*(C`decode\*(C'\fR in any way, and it is recommended to leave it off unless you know your communications partner. .ie n .IP "$json = $json\->allow_blessed ([$enable])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->allow_blessed ([$enable])" 4 .IX Item "$json = $json->allow_blessed ([$enable])" .PD 0 .ie n .IP "$enabled = $json\->get_allow_blessed" 4 .el .IP "\f(CW$enabled\fR = \f(CW$json\fR\->get_allow_blessed" 4 .IX Item "$enabled = $json->get_allow_blessed" .PD See \*(L"\s-1OBJECT SERIALISATION\*(R"\s0 for details. .Sp If \f(CW$enable\fR is true (or missing), then the \f(CW\*(C`encode\*(C'\fR method will not barf when it encounters a blessed reference that it cannot convert otherwise. Instead, a \s-1JSON\s0 \f(CW\*(C`null\*(C'\fR value is encoded instead of the object. .Sp If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will throw an exception when it encounters a blessed object that it cannot convert otherwise. .Sp This setting has no effect on \f(CW\*(C`decode\*(C'\fR. .ie n .IP "$json = $json\->convert_blessed ([$enable])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->convert_blessed ([$enable])" 4 .IX Item "$json = $json->convert_blessed ([$enable])" .PD 0 .ie n .IP "$enabled = $json\->get_convert_blessed" 4 .el .IP "\f(CW$enabled\fR = \f(CW$json\fR\->get_convert_blessed" 4 .IX Item "$enabled = $json->get_convert_blessed" .PD See \*(L"\s-1OBJECT SERIALISATION\*(R"\s0 for details. .Sp If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR, upon encountering a blessed object, will check for the availability of the \f(CW\*(C`TO_JSON\*(C'\fR method on the object's class. If found, it will be called in scalar context and the resulting scalar will be encoded instead of the object. .Sp The \f(CW\*(C`TO_JSON\*(C'\fR method may safely call die if it wants. If \f(CW\*(C`TO_JSON\*(C'\fR returns other blessed objects, those will be handled in the same way. \f(CW\*(C`TO_JSON\*(C'\fR must take care of not causing an endless recursion cycle (== crash) in this case. The name of \f(CW\*(C`TO_JSON\*(C'\fR was chosen because other methods called by the Perl core (== not by the user of the object) are usually in upper case letters and to avoid collisions with any \f(CW\*(C`to_json\*(C'\fR function or method. .Sp If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will not consider this type of conversion. .Sp This setting has no effect on \f(CW\*(C`decode\*(C'\fR. .ie n .IP "$json = $json\->allow_tags ([$enable])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->allow_tags ([$enable])" 4 .IX Item "$json = $json->allow_tags ([$enable])" .PD 0 .ie n .IP "$enabled = $json\->get_allow_tags" 4 .el .IP "\f(CW$enabled\fR = \f(CW$json\fR\->get_allow_tags" 4 .IX Item "$enabled = $json->get_allow_tags" .PD See \*(L"\s-1OBJECT SERIALISATION\*(R"\s0 for details. .Sp If \f(CW$enable\fR is true (or missing), then \f(CW\*(C`encode\*(C'\fR, upon encountering a blessed object, will check for the availability of the \f(CW\*(C`FREEZE\*(C'\fR method on the object's class. If found, it will be used to serialise the object into a nonstandard tagged \s-1JSON\s0 value (that \s-1JSON\s0 decoders cannot decode). .Sp It also causes \f(CW\*(C`decode\*(C'\fR to parse such tagged \s-1JSON\s0 values and deserialise them via a call to the \f(CW\*(C`THAW\*(C'\fR method. .Sp If \f(CW$enable\fR is false (the default), then \f(CW\*(C`encode\*(C'\fR will not consider this type of conversion, and tagged \s-1JSON\s0 values will cause a parse error in \f(CW\*(C`decode\*(C'\fR, as if tags were not part of the grammar. .ie n .IP "$json\->boolean_values ([$false, $true])" 4 .el .IP "\f(CW$json\fR\->boolean_values ([$false, \f(CW$true\fR])" 4 .IX Item "$json->boolean_values ([$false, $true])" .PD 0 .ie n .IP "($false, $true) = $json\->get_boolean_values" 4 .el .IP "($false, \f(CW$true\fR) = \f(CW$json\fR\->get_boolean_values" 4 .IX Item "($false, $true) = $json->get_boolean_values" .PD By default, \s-1JSON\s0 booleans will be decoded as overloaded \&\f(CW$Types::Serialiser::false\fR and \f(CW$Types::Serialiser::true\fR objects. .Sp With this method you can specify your own boolean values for decoding \- on decode, \s-1JSON\s0 \f(CW\*(C`false\*(C'\fR will be decoded as a copy of \f(CW$false\fR, and \s-1JSON\s0 \&\f(CW\*(C`true\*(C'\fR will be decoded as \f(CW$true\fR (\*(L"copy\*(R" here is the same thing as assigning a value to another variable, i.e. \f(CW\*(C`$copy = $false\*(C'\fR). .Sp Calling this method without any arguments will reset the booleans to their default values. .Sp \&\f(CW\*(C`get_boolean_values\*(C'\fR will return both \f(CW$false\fR and \f(CW$true\fR values, or the empty list when they are set to the default. .ie n .IP "$json = $json\->filter_json_object ([$coderef\->($hashref)])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->filter_json_object ([$coderef\->($hashref)])" 4 .IX Item "$json = $json->filter_json_object ([$coderef->($hashref)])" When \f(CW$coderef\fR is specified, it will be called from \f(CW\*(C`decode\*(C'\fR each time it decodes a \s-1JSON\s0 object. The only argument is a reference to the newly-created hash. If the code reference returns a single scalar (which need not be a reference), this value (or rather a copy of it) is inserted into the deserialised data structure. If it returns an empty list (\s-1NOTE:\s0 \fInot\fR \f(CW\*(C`undef\*(C'\fR, which is a valid scalar), the original deserialised hash will be inserted. This setting can slow down decoding considerably. .Sp When \f(CW$coderef\fR is omitted or undefined, any existing callback will be removed and \f(CW\*(C`decode\*(C'\fR will not change the deserialised hash in any way. .Sp Example, convert all \s-1JSON\s0 objects into the integer 5: .Sp .Vb 6 \& my $js = JSON::XS\->new\->filter_json_object (sub { 5 }); \& # returns [5] \& $js\->decode (\*(Aq[{}]\*(Aq) \& # throw an exception because allow_nonref is not enabled \& # so a lone 5 is not allowed. \& $js\->decode (\*(Aq{"a":1, "b":2}\*(Aq); .Ve .ie n .IP "$json = $json\->filter_json_single_key_object ($key [=> $coderef\->($value)])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->filter_json_single_key_object ($key [=> \f(CW$coderef\fR\->($value)])" 4 .IX Item "$json = $json->filter_json_single_key_object ($key [=> $coderef->($value)])" Works remotely similar to \f(CW\*(C`filter_json_object\*(C'\fR, but is only called for \&\s-1JSON\s0 objects having a single key named \f(CW$key\fR. .Sp This \f(CW$coderef\fR is called before the one specified via \&\f(CW\*(C`filter_json_object\*(C'\fR, if any. It gets passed the single value in the \s-1JSON\s0 object. If it returns a single value, it will be inserted into the data structure. If it returns nothing (not even \f(CW\*(C`undef\*(C'\fR but the empty list), the callback from \f(CW\*(C`filter_json_object\*(C'\fR will be called next, as if no single-key callback were specified. .Sp If \f(CW$coderef\fR is omitted or undefined, the corresponding callback will be disabled. There can only ever be one callback for a given key. .Sp As this callback gets called less often then the \f(CW\*(C`filter_json_object\*(C'\fR one, decoding speed will not usually suffer as much. Therefore, single-key objects make excellent targets to serialise Perl objects into, especially as single-key \s-1JSON\s0 objects are as close to the type-tagged value concept as \s-1JSON\s0 gets (it's basically an \s-1ID/VALUE\s0 tuple). Of course, \s-1JSON\s0 does not support this in any way, so you need to make sure your data never looks like a serialised Perl hash. .Sp Typical names for the single object key are \f(CW\*(C`_\|_class_whatever_\|_\*(C'\fR, or \&\f(CW\*(C`$_\|_dollars_are_rarely_used_\|_$\*(C'\fR or \f(CW\*(C`}ugly_brace_placement\*(C'\fR, or even things like \f(CW\*(C`_\|_class_md5sum(classname)_\|_\*(C'\fR, to reduce the risk of clashing with real hashes. .Sp Example, decode \s-1JSON\s0 objects of the form \f(CW\*(C`{ "_\|_widget_\|_" => }\*(C'\fR into the corresponding \f(CW$WIDGET{}\fR object: .Sp .Vb 7 \& # return whatever is in $WIDGET{5}: \& JSON::XS \& \->new \& \->filter_json_single_key_object (_\|_widget_\|_ => sub { \& $WIDGET{ $_[0] } \& }) \& \->decode (\*(Aq{"_\|_widget_\|_": 5\*(Aq) \& \& # this can be used with a TO_JSON method in some "widget" class \& # for serialisation to json: \& sub WidgetBase::TO_JSON { \& my ($self) = @_; \& \& unless ($self\->{id}) { \& $self\->{id} = ..get..some..id..; \& $WIDGET{$self\->{id}} = $self; \& } \& \& { _\|_widget_\|_ => $self\->{id} } \& } .Ve .ie n .IP "$json = $json\->shrink ([$enable])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->shrink ([$enable])" 4 .IX Item "$json = $json->shrink ([$enable])" .PD 0 .ie n .IP "$enabled = $json\->get_shrink" 4 .el .IP "\f(CW$enabled\fR = \f(CW$json\fR\->get_shrink" 4 .IX Item "$enabled = $json->get_shrink" .PD Perl usually over-allocates memory a bit when allocating space for strings. This flag optionally resizes strings generated by either \&\f(CW\*(C`encode\*(C'\fR or \f(CW\*(C`decode\*(C'\fR to their minimum size possible. This can save memory when your \s-1JSON\s0 texts are either very very long or you have many short strings. It will also try to downgrade any strings to octet-form if possible: perl stores strings internally either in an encoding called UTF-X or in octet-form. The latter cannot store everything but uses less space in general (and some buggy Perl or C code might even rely on that internal representation being used). .Sp The actual definition of what shrink does might change in future versions, but it will always try to save space at the expense of time. .Sp If \f(CW$enable\fR is true (or missing), the string returned by \f(CW\*(C`encode\*(C'\fR will be shrunk-to-fit, while all strings generated by \f(CW\*(C`decode\*(C'\fR will also be shrunk-to-fit. .Sp If \f(CW$enable\fR is false, then the normal perl allocation algorithms are used. If you work with your data, then this is likely to be faster. .Sp In the future, this setting might control other things, such as converting strings that look like integers or floats into integers or floats internally (there is no difference on the Perl level), saving space. .ie n .IP "$json = $json\->max_depth ([$maximum_nesting_depth])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->max_depth ([$maximum_nesting_depth])" 4 .IX Item "$json = $json->max_depth ([$maximum_nesting_depth])" .PD 0 .ie n .IP "$max_depth = $json\->get_max_depth" 4 .el .IP "\f(CW$max_depth\fR = \f(CW$json\fR\->get_max_depth" 4 .IX Item "$max_depth = $json->get_max_depth" .PD Sets the maximum nesting level (default \f(CW512\fR) accepted while encoding or decoding. If a higher nesting level is detected in \s-1JSON\s0 text or a Perl data structure, then the encoder and decoder will stop and croak at that point. .Sp Nesting level is defined by number of hash\- or arrayrefs that the encoder needs to traverse to reach a given point or the number of \f(CW\*(C`{\*(C'\fR or \f(CW\*(C`[\*(C'\fR characters without their matching closing parenthesis crossed to reach a given character in a string. .Sp Setting the maximum depth to one disallows any nesting, so that ensures that the object is only a single hash/object or array. .Sp If no argument is given, the highest possible setting will be used, which is rarely useful. .Sp Note that nesting is implemented by recursion in C. The default value has been chosen to be as large as typical operating systems allow without crashing. .Sp See \s-1SECURITY CONSIDERATIONS,\s0 below, for more info on why this is useful. .ie n .IP "$json = $json\->max_size ([$maximum_string_size])" 4 .el .IP "\f(CW$json\fR = \f(CW$json\fR\->max_size ([$maximum_string_size])" 4 .IX Item "$json = $json->max_size ([$maximum_string_size])" .PD 0 .ie n .IP "$max_size = $json\->get_max_size" 4 .el .IP "\f(CW$max_size\fR = \f(CW$json\fR\->get_max_size" 4 .IX Item "$max_size = $json->get_max_size" .PD Set the maximum length a \s-1JSON\s0 text may have (in bytes) where decoding is being attempted. The default is \f(CW0\fR, meaning no limit. When \f(CW\*(C`decode\*(C'\fR is called on a string that is longer then this many bytes, it will not attempt to decode the string but throw an exception. This setting has no effect on \f(CW\*(C`encode\*(C'\fR (yet). .Sp If no argument is given, the limit check will be deactivated (same as when \&\f(CW0\fR is specified). .Sp See \s-1SECURITY CONSIDERATIONS,\s0 below, for more info on why this is useful. .ie n .IP "$json_text = $json\->encode ($perl_scalar)" 4 .el .IP "\f(CW$json_text\fR = \f(CW$json\fR\->encode ($perl_scalar)" 4 .IX Item "$json_text = $json->encode ($perl_scalar)" Converts the given Perl value or data structure to its \s-1JSON\s0 representation. Croaks on error. .ie n .IP "$perl_scalar = $json\->decode ($json_text)" 4 .el .IP "\f(CW$perl_scalar\fR = \f(CW$json\fR\->decode ($json_text)" 4 .IX Item "$perl_scalar = $json->decode ($json_text)" The opposite of \f(CW\*(C`encode\*(C'\fR: expects a \s-1JSON\s0 text and tries to parse it, returning the resulting simple scalar or reference. Croaks on error. .ie n .IP "($perl_scalar, $characters) = $json\->decode_prefix ($json_text)" 4 .el .IP "($perl_scalar, \f(CW$characters\fR) = \f(CW$json\fR\->decode_prefix ($json_text)" 4 .IX Item "($perl_scalar, $characters) = $json->decode_prefix ($json_text)" This works like the \f(CW\*(C`decode\*(C'\fR method, but instead of raising an exception when there is trailing garbage after the first \s-1JSON\s0 object, it will silently stop parsing there and return the number of characters consumed so far. .Sp This is useful if your \s-1JSON\s0 texts are not delimited by an outer protocol and you need to know where the \s-1JSON\s0 text ends. .Sp .Vb 2 \& JSON::XS\->new\->decode_prefix ("[1] the tail") \& => ([1], 3) .Ve .SH "INCREMENTAL PARSING" .IX Header "INCREMENTAL PARSING" In some cases, there is the need for incremental parsing of \s-1JSON\s0 texts. While this module always has to keep both \s-1JSON\s0 text and resulting Perl data structure in memory at one time, it does allow you to parse a \&\s-1JSON\s0 stream incrementally. It does so by accumulating text until it has a full \s-1JSON\s0 object, which it then can decode. This process is similar to using \f(CW\*(C`decode_prefix\*(C'\fR to see if a full \s-1JSON\s0 object is available, but is much more efficient (and can be implemented with a minimum of method calls). .PP \&\s-1JSON::XS\s0 will only attempt to parse the \s-1JSON\s0 text once it is sure it has enough text to get a decisive result, using a very simple but truly incremental parser. This means that it sometimes won't stop as early as the full parser, for example, it doesn't detect mismatched parentheses. The only thing it guarantees is that it starts decoding as soon as a syntactically valid \s-1JSON\s0 text has been seen. This means you need to set resource limits (e.g. \f(CW\*(C`max_size\*(C'\fR) to ensure the parser will stop parsing in the presence if syntax errors. .PP The following methods implement this incremental parser. .ie n .IP "[void, scalar or list context] = $json\->incr_parse ([$string])" 4 .el .IP "[void, scalar or list context] = \f(CW$json\fR\->incr_parse ([$string])" 4 .IX Item "[void, scalar or list context] = $json->incr_parse ([$string])" This is the central parsing function. It can both append new text and extract objects from the stream accumulated so far (both of these functions are optional). .Sp If \f(CW$string\fR is given, then this string is appended to the already existing \s-1JSON\s0 fragment stored in the \f(CW$json\fR object. .Sp After that, if the function is called in void context, it will simply return without doing anything further. This can be used to add more text in as many chunks as you want. .Sp If the method is called in scalar context, then it will try to extract exactly \fIone\fR \s-1JSON\s0 object. If that is successful, it will return this object, otherwise it will return \f(CW\*(C`undef\*(C'\fR. If there is a parse error, this method will croak just as \f(CW\*(C`decode\*(C'\fR would do (one can then use \&\f(CW\*(C`incr_skip\*(C'\fR to skip the erroneous part). This is the most common way of using the method. .Sp And finally, in list context, it will try to extract as many objects from the stream as it can find and return them, or the empty list otherwise. For this to work, there must be no separators (other than whitespace) between the \s-1JSON\s0 objects or arrays, instead they must be concatenated back-to-back. If an error occurs, an exception will be raised as in the scalar context case. Note that in this case, any previously-parsed \s-1JSON\s0 texts will be lost. .Sp Example: Parse some \s-1JSON\s0 arrays/objects in a given string and return them. .Sp .Vb 1 \& my @objs = JSON::XS\->new\->incr_parse ("[5][7][1,2]"); .Ve .ie n .IP "$lvalue_string = $json\->incr_text" 4 .el .IP "\f(CW$lvalue_string\fR = \f(CW$json\fR\->incr_text" 4 .IX Item "$lvalue_string = $json->incr_text" This method returns the currently stored \s-1JSON\s0 fragment as an lvalue, that is, you can manipulate it. This \fIonly\fR works when a preceding call to \&\f(CW\*(C`incr_parse\*(C'\fR in \fIscalar context\fR successfully returned an object. Under all other circumstances you must not call this function (I mean it. although in simple tests it might actually work, it \fIwill\fR fail under real world conditions). As a special exception, you can also call this method before having parsed anything. .Sp That means you can only use this function to look at or manipulate text before or after complete \s-1JSON\s0 objects, not while the parser is in the middle of parsing a \s-1JSON\s0 object. .Sp This function is useful in two cases: a) finding the trailing text after a \&\s-1JSON\s0 object or b) parsing multiple \s-1JSON\s0 objects separated by non-JSON text (such as commas). .ie n .IP "$json\->incr_skip" 4 .el .IP "\f(CW$json\fR\->incr_skip" 4 .IX Item "$json->incr_skip" This will reset the state of the incremental parser and will remove the parsed text from the input buffer so far. This is useful after \&\f(CW\*(C`incr_parse\*(C'\fR died, in which case the input buffer and incremental parser state is left unchanged, to skip the text parsed so far and to reset the parse state. .Sp The difference to \f(CW\*(C`incr_reset\*(C'\fR is that only text until the parse error occurred is removed. .ie n .IP "$json\->incr_reset" 4 .el .IP "\f(CW$json\fR\->incr_reset" 4 .IX Item "$json->incr_reset" This completely resets the incremental parser, that is, after this call, it will be as if the parser had never parsed anything. .Sp This is useful if you want to repeatedly parse \s-1JSON\s0 objects and want to ignore any trailing data, which means you have to reset the parser after each successful decode. .SS "\s-1LIMITATIONS\s0" .IX Subsection "LIMITATIONS" The incremental parser is a non-exact parser: it works by gathering as much text as possible that \fIcould\fR be a valid \s-1JSON\s0 text, followed by trying to decode it. .PP That means it sometimes needs to read more data than strictly necessary to diagnose an invalid \s-1JSON\s0 text. For example, after parsing the following fragment, the parser \fIcould\fR stop with an error, as this fragment \&\fIcannot\fR be the beginning of a valid \s-1JSON\s0 text: .PP .Vb 1 \& [, .Ve .PP In reality, hopwever, the parser might continue to read data until a length limit is exceeded or it finds a closing bracket. .SS "\s-1EXAMPLES\s0" .IX Subsection "EXAMPLES" Some examples will make all this clearer. First, a simple example that works similarly to \f(CW\*(C`decode_prefix\*(C'\fR: We want to decode the \s-1JSON\s0 object at the start of a string and identify the portion after the \s-1JSON\s0 object: .PP .Vb 1 \& my $text = "[1,2,3] hello"; \& \& my $json = new JSON::XS; \& \& my $obj = $json\->incr_parse ($text) \& or die "expected JSON object or array at beginning of string"; \& \& my $tail = $json\->incr_text; \& # $tail now contains " hello" .Ve .PP Easy, isn't it? .PP Now for a more complicated example: Imagine a hypothetical protocol where you read some requests from a \s-1TCP\s0 stream, and each request is a \s-1JSON\s0 array, without any separation between them (in fact, it is often useful to use newlines as \*(L"separators\*(R", as these get interpreted as whitespace at the start of the \s-1JSON\s0 text, which makes it possible to test said protocol with \f(CW\*(C`telnet\*(C'\fR...). .PP Here is how you'd do it (it is trivial to write this in an event-based manner): .PP .Vb 1 \& my $json = new JSON::XS; \& \& # read some data from the socket \& while (sysread $socket, my $buf, 4096) { \& \& # split and decode as many requests as possible \& for my $request ($json\->incr_parse ($buf)) { \& # act on the $request \& } \& } .Ve .PP Another complicated example: Assume you have a string with \s-1JSON\s0 objects or arrays, all separated by (optional) comma characters (e.g. \f(CW\*(C`[1],[2], [3]\*(C'\fR). To parse them, we have to skip the commas between the \s-1JSON\s0 texts, and here is where the lvalue-ness of \f(CW\*(C`incr_text\*(C'\fR comes in useful: .PP .Vb 2 \& my $text = "[1],[2], [3]"; \& my $json = new JSON::XS; \& \& # void context, so no parsing done \& $json\->incr_parse ($text); \& \& # now extract as many objects as possible. note the \& # use of scalar context so incr_text can be called. \& while (my $obj = $json\->incr_parse) { \& # do something with $obj \& \& # now skip the optional comma \& $json\->incr_text =~ s/^ \es* , //x; \& } .Ve .PP Now lets go for a very complex example: Assume that you have a gigantic \&\s-1JSON\s0 array-of-objects, many gigabytes in size, and you want to parse it, but you cannot load it into memory fully (this has actually happened in the real world :). .PP Well, you lost, you have to implement your own \s-1JSON\s0 parser. But \s-1JSON::XS\s0 can still help you: You implement a (very simple) array parser and let \&\s-1JSON\s0 decode the array elements, which are all full \s-1JSON\s0 objects on their own (this wouldn't work if the array elements could be \s-1JSON\s0 numbers, for example): .PP .Vb 1 \& my $json = new JSON::XS; \& \& # open the monster \& open my $fh, "incr_parse ($buf); # void context, so no parsing \& \& # Exit the loop once we found and removed(!) the initial "[". \& # In essence, we are (ab\-)using the $json object as a simple scalar \& # we append data to. \& last if $json\->incr_text =~ s/^ \es* \e[ //x; \& } \& \& # now we have the skipped the initial "[", so continue \& # parsing all the elements. \& for (;;) { \& # in this loop we read data until we got a single JSON object \& for (;;) { \& if (my $obj = $json\->incr_parse) { \& # do something with $obj \& last; \& } \& \& # add more data \& sysread $fh, my $buf, 65536 \& or die "read error: $!"; \& $json\->incr_parse ($buf); # void context, so no parsing \& } \& \& # in this loop we read data until we either found and parsed the \& # separating "," between elements, or the final "]" \& for (;;) { \& # first skip whitespace \& $json\->incr_text =~ s/^\es*//; \& \& # if we find "]", we are done \& if ($json\->incr_text =~ s/^\e]//) { \& print "finished.\en"; \& exit; \& } \& \& # if we find ",", we can continue with the next element \& if ($json\->incr_text =~ s/^,//) { \& last; \& } \& \& # if we find anything else, we have a parse error! \& if (length $json\->incr_text) { \& die "parse error near ", $json\->incr_text; \& } \& \& # else add more data \& sysread $fh, my $buf, 65536 \& or die "read error: $!"; \& $json\->incr_parse ($buf); # void context, so no parsing \& } .Ve .PP This is a complex example, but most of the complexity comes from the fact that we are trying to be correct (bear with me if I am wrong, I never ran the above example :). .SH "MAPPING" .IX Header "MAPPING" This section describes how \s-1JSON::XS\s0 maps Perl values to \s-1JSON\s0 values and vice versa. These mappings are designed to \*(L"do the right thing\*(R" in most circumstances automatically, preserving round-tripping characteristics (what you put in comes out as something equivalent). .PP For the more enlightened: note that in the following descriptions, lowercase \fIperl\fR refers to the Perl interpreter, while uppercase \fIPerl\fR refers to the abstract Perl language itself. .SS "\s-1JSON\s0 \-> \s-1PERL\s0" .IX Subsection "JSON -> PERL" .IP "object" 4 .IX Item "object" A \s-1JSON\s0 object becomes a reference to a hash in Perl. No ordering of object keys is preserved (\s-1JSON\s0 does not preserve object key ordering itself). .IP "array" 4 .IX Item "array" A \s-1JSON\s0 array becomes a reference to an array in Perl. .IP "string" 4 .IX Item "string" A \s-1JSON\s0 string becomes a string scalar in Perl \- Unicode codepoints in \s-1JSON\s0 are represented by the same codepoints in the Perl string, so no manual decoding is necessary. .IP "number" 4 .IX Item "number" A \s-1JSON\s0 number becomes either an integer, numeric (floating point) or string scalar in perl, depending on its range and any fractional parts. On the Perl level, there is no difference between those as Perl handles all the conversion details, but an integer may take slightly less memory and might represent more values exactly than floating point numbers. .Sp If the number consists of digits only, \s-1JSON::XS\s0 will try to represent it as an integer value. If that fails, it will try to represent it as a numeric (floating point) value if that is possible without loss of precision. Otherwise it will preserve the number as a string value (in which case you lose roundtripping ability, as the \s-1JSON\s0 number will be re-encoded to a \s-1JSON\s0 string). .Sp Numbers containing a fractional or exponential part will always be represented as numeric (floating point) values, possibly at a loss of precision (in which case you might lose perfect roundtripping ability, but the \s-1JSON\s0 number will still be re-encoded as a \s-1JSON\s0 number). .Sp Note that precision is not accuracy \- binary floating point values cannot represent most decimal fractions exactly, and when converting from and to floating point, \s-1JSON::XS\s0 only guarantees precision up to but not including the least significant bit. .IP "true, false" 4 .IX Item "true, false" These \s-1JSON\s0 atoms become \f(CW\*(C`Types::Serialiser::true\*(C'\fR and \&\f(CW\*(C`Types::Serialiser::false\*(C'\fR, respectively. They are overloaded to act almost exactly like the numbers \f(CW1\fR and \f(CW0\fR. You can check whether a scalar is a \s-1JSON\s0 boolean by using the \f(CW\*(C`Types::Serialiser::is_bool\*(C'\fR function (after \f(CW\*(C`use Types::Serialier\*(C'\fR, of course). .IP "null" 4 .IX Item "null" A \s-1JSON\s0 null atom becomes \f(CW\*(C`undef\*(C'\fR in Perl. .ie n .IP "shell-style comments (""# \fItext\fP"")" 4 .el .IP "shell-style comments (\f(CW# \f(CItext\f(CW\fR)" 4 .IX Item "shell-style comments (# text)" As a nonstandard extension to the \s-1JSON\s0 syntax that is enabled by the \&\f(CW\*(C`relaxed\*(C'\fR setting, shell-style comments are allowed. They can start anywhere outside strings and go till the end of the line. .ie n .IP "tagged values (""(\fItag\fP)\fIvalue\fP"")." 4 .el .IP "tagged values (\f(CW(\f(CItag\f(CW)\f(CIvalue\f(CW\fR)." 4 .IX Item "tagged values ((tag)value)." Another nonstandard extension to the \s-1JSON\s0 syntax, enabled with the \&\f(CW\*(C`allow_tags\*(C'\fR setting, are tagged values. In this implementation, the \&\fItag\fR must be a perl package/class name encoded as a \s-1JSON\s0 string, and the \&\fIvalue\fR must be a \s-1JSON\s0 array encoding optional constructor arguments. .Sp See \*(L"\s-1OBJECT SERIALISATION\*(R"\s0, below, for details. .SS "\s-1PERL\s0 \-> \s-1JSON\s0" .IX Subsection "PERL -> JSON" The mapping from Perl to \s-1JSON\s0 is slightly more difficult, as Perl is a truly typeless language, so we can only guess which \s-1JSON\s0 type is meant by a Perl value. .IP "hash references" 4 .IX Item "hash references" Perl hash references become \s-1JSON\s0 objects. As there is no inherent ordering in hash keys (or \s-1JSON\s0 objects), they will usually be encoded in a pseudo-random order. \s-1JSON::XS\s0 can optionally sort the hash keys (determined by the \fIcanonical\fR flag), so the same datastructure will serialise to the same \s-1JSON\s0 text (given same settings and version of \&\s-1JSON::XS\s0), but this incurs a runtime overhead and is only rarely useful, e.g. when you want to compare some \s-1JSON\s0 text against another for equality. .IP "array references" 4 .IX Item "array references" Perl array references become \s-1JSON\s0 arrays. .IP "other references" 4 .IX Item "other references" Other unblessed references are generally not allowed and will cause an exception to be thrown, except for references to the integers \f(CW0\fR and \&\f(CW1\fR, which get turned into \f(CW\*(C`false\*(C'\fR and \f(CW\*(C`true\*(C'\fR atoms in \s-1JSON.\s0 .Sp Since \f(CW\*(C`JSON::XS\*(C'\fR uses the boolean model from Types::Serialiser, you can also \f(CW\*(C`use Types::Serialiser\*(C'\fR and then use \f(CW\*(C`Types::Serialiser::false\*(C'\fR and \f(CW\*(C`Types::Serialiser::true\*(C'\fR to improve readability. .Sp .Vb 2 \& use Types::Serialiser; \& encode_json [\e0, Types::Serialiser::true] # yields [false,true] .Ve .IP "Types::Serialiser::true, Types::Serialiser::false" 4 .IX Item "Types::Serialiser::true, Types::Serialiser::false" These special values from the Types::Serialiser module become \s-1JSON\s0 true and \s-1JSON\s0 false values, respectively. You can also use \f(CW\*(C`\e1\*(C'\fR and \f(CW\*(C`\e0\*(C'\fR directly if you want. .IP "blessed objects" 4 .IX Item "blessed objects" Blessed objects are not directly representable in \s-1JSON,\s0 but \f(CW\*(C`JSON::XS\*(C'\fR allows various ways of handling objects. See \*(L"\s-1OBJECT SERIALISATION\*(R"\s0, below, for details. .IP "simple scalars" 4 .IX Item "simple scalars" Simple Perl scalars (any scalar that is not a reference) are the most difficult objects to encode: \s-1JSON::XS\s0 will encode undefined scalars as \&\s-1JSON\s0 \f(CW\*(C`null\*(C'\fR values, scalars that have last been used in a string context before encoding as \s-1JSON\s0 strings, and anything else as number value: .Sp .Vb 4 \& # dump as number \& encode_json [2] # yields [2] \& encode_json [\-3.0e17] # yields [\-3e+17] \& my $value = 5; encode_json [$value] # yields [5] \& \& # used as string, so dump as string \& print $value; \& encode_json [$value] # yields ["5"] \& \& # undef becomes null \& encode_json [undef] # yields [null] .Ve .Sp You can force the type to be a \s-1JSON\s0 string by stringifying it: .Sp .Vb 4 \& my $x = 3.1; # some variable containing a number \& "$x"; # stringified \& $x .= ""; # another, more awkward way to stringify \& print $x; # perl does it for you, too, quite often .Ve .Sp You can force the type to be a \s-1JSON\s0 number by numifying it: .Sp .Vb 3 \& my $x = "3"; # some variable containing a string \& $x += 0; # numify it, ensuring it will be dumped as a number \& $x *= 1; # same thing, the choice is yours. .Ve .Sp You can not currently force the type in other, less obscure, ways. Tell me if you need this capability (but don't forget to explain why it's needed :). .Sp Note that numerical precision has the same meaning as under Perl (so binary to decimal conversion follows the same rules as in Perl, which can differ to other languages). Also, your perl interpreter might expose extensions to the floating point numbers of your platform, such as infinities or NaN's \- these cannot be represented in \s-1JSON,\s0 and it is an error to pass those in. .SS "\s-1OBJECT SERIALISATION\s0" .IX Subsection "OBJECT SERIALISATION" As \s-1JSON\s0 cannot directly represent Perl objects, you have to choose between a pure \s-1JSON\s0 representation (without the ability to deserialise the object automatically again), and a nonstandard extension to the \s-1JSON\s0 syntax, tagged values. .PP \fI\s-1SERIALISATION\s0\fR .IX Subsection "SERIALISATION" .PP What happens when \f(CW\*(C`JSON::XS\*(C'\fR encounters a Perl object depends on the \&\f(CW\*(C`allow_blessed\*(C'\fR, \f(CW\*(C`convert_blessed\*(C'\fR and \f(CW\*(C`allow_tags\*(C'\fR settings, which are used in this order: .ie n .IP "1. ""allow_tags"" is enabled and the object has a ""FREEZE"" method." 4 .el .IP "1. \f(CWallow_tags\fR is enabled and the object has a \f(CWFREEZE\fR method." 4 .IX Item "1. allow_tags is enabled and the object has a FREEZE method." In this case, \f(CW\*(C`JSON::XS\*(C'\fR uses the Types::Serialiser object serialisation protocol to create a tagged \s-1JSON\s0 value, using a nonstandard extension to the \s-1JSON\s0 syntax. .Sp This works by invoking the \f(CW\*(C`FREEZE\*(C'\fR method on the object, with the first argument being the object to serialise, and the second argument being the constant string \f(CW\*(C`JSON\*(C'\fR to distinguish it from other serialisers. .Sp The \f(CW\*(C`FREEZE\*(C'\fR method can return any number of values (i.e. zero or more). These values and the paclkage/classname of the object will then be encoded as a tagged \s-1JSON\s0 value in the following format: .Sp .Vb 1 \& ("classname")[FREEZE return values...] .Ve .Sp e.g.: .Sp .Vb 3 \& ("URI")["http://www.google.com/"] \& ("MyDate")[2013,10,29] \& ("ImageData::JPEG")["Z3...VlCg=="] .Ve .Sp For example, the hypothetical \f(CW\*(C`My::Object\*(C'\fR \f(CW\*(C`FREEZE\*(C'\fR method might use the objects \f(CW\*(C`type\*(C'\fR and \f(CW\*(C`id\*(C'\fR members to encode the object: .Sp .Vb 2 \& sub My::Object::FREEZE { \& my ($self, $serialiser) = @_; \& \& ($self\->{type}, $self\->{id}) \& } .Ve .ie n .IP "2. ""convert_blessed"" is enabled and the object has a ""TO_JSON"" method." 4 .el .IP "2. \f(CWconvert_blessed\fR is enabled and the object has a \f(CWTO_JSON\fR method." 4 .IX Item "2. convert_blessed is enabled and the object has a TO_JSON method." In this case, the \f(CW\*(C`TO_JSON\*(C'\fR method of the object is invoked in scalar context. It must return a single scalar that can be directly encoded into \&\s-1JSON.\s0 This scalar replaces the object in the \s-1JSON\s0 text. .Sp For example, the following \f(CW\*(C`TO_JSON\*(C'\fR method will convert all \s-1URI\s0 objects to \s-1JSON\s0 strings when serialised. The fatc that these values originally were \s-1URI\s0 objects is lost. .Sp .Vb 4 \& sub URI::TO_JSON { \& my ($uri) = @_; \& $uri\->as_string \& } .Ve .ie n .IP "3. ""allow_blessed"" is enabled." 4 .el .IP "3. \f(CWallow_blessed\fR is enabled." 4 .IX Item "3. allow_blessed is enabled." The object will be serialised as a \s-1JSON\s0 null value. .IP "4. none of the above" 4 .IX Item "4. none of the above" If none of the settings are enabled or the respective methods are missing, \&\f(CW\*(C`JSON::XS\*(C'\fR throws an exception. .PP \fI\s-1DESERIALISATION\s0\fR .IX Subsection "DESERIALISATION" .PP For deserialisation there are only two cases to consider: either nonstandard tagging was used, in which case \f(CW\*(C`allow_tags\*(C'\fR decides, or objects cannot be automatically be deserialised, in which case you can use postprocessing or the \f(CW\*(C`filter_json_object\*(C'\fR or \&\f(CW\*(C`filter_json_single_key_object\*(C'\fR callbacks to get some real objects our of your \s-1JSON.\s0 .PP This section only considers the tagged value case: I a tagged \s-1JSON\s0 object is encountered during decoding and \f(CW\*(C`allow_tags\*(C'\fR is disabled, a parse error will result (as if tagged values were not part of the grammar). .PP If \f(CW\*(C`allow_tags\*(C'\fR is enabled, \f(CW\*(C`JSON::XS\*(C'\fR will look up the \f(CW\*(C`THAW\*(C'\fR method of the package/classname used during serialisation (it will not attempt to load the package as a Perl module). If there is no such method, the decoding will fail with an error. .PP Otherwise, the \f(CW\*(C`THAW\*(C'\fR method is invoked with the classname as first argument, the constant string \f(CW\*(C`JSON\*(C'\fR as second argument, and all the values from the \s-1JSON\s0 array (the values originally returned by the \&\f(CW\*(C`FREEZE\*(C'\fR method) as remaining arguments. .PP The method must then return the object. While technically you can return any Perl scalar, you might have to enable the \f(CW\*(C`enable_nonref\*(C'\fR setting to make that work in all cases, so better return an actual blessed reference. .PP As an example, let's implement a \f(CW\*(C`THAW\*(C'\fR function that regenerates the \&\f(CW\*(C`My::Object\*(C'\fR from the \f(CW\*(C`FREEZE\*(C'\fR example earlier: .PP .Vb 2 \& sub My::Object::THAW { \& my ($class, $serialiser, $type, $id) = @_; \& \& $class\->new (type => $type, id => $id) \& } .Ve .SH "ENCODING/CODESET FLAG NOTES" .IX Header "ENCODING/CODESET FLAG NOTES" The interested reader might have seen a number of flags that signify encodings or codesets \- \f(CW\*(C`utf8\*(C'\fR, \f(CW\*(C`latin1\*(C'\fR and \f(CW\*(C`ascii\*(C'\fR. There seems to be some confusion on what these do, so here is a short comparison: .PP \&\f(CW\*(C`utf8\*(C'\fR controls whether the \s-1JSON\s0 text created by \f(CW\*(C`encode\*(C'\fR (and expected by \f(CW\*(C`decode\*(C'\fR) is \s-1UTF\-8\s0 encoded or not, while \f(CW\*(C`latin1\*(C'\fR and \f(CW\*(C`ascii\*(C'\fR only control whether \f(CW\*(C`encode\*(C'\fR escapes character values outside their respective codeset range. Neither of these flags conflict with each other, although some combinations make less sense than others. .PP Care has been taken to make all flags symmetrical with respect to \&\f(CW\*(C`encode\*(C'\fR and \f(CW\*(C`decode\*(C'\fR, that is, texts encoded with any combination of these flag values will be correctly decoded when the same flags are used \&\- in general, if you use different flag settings while encoding vs. when decoding you likely have a bug somewhere. .PP Below comes a verbose discussion of these flags. Note that a \*(L"codeset\*(R" is simply an abstract set of character-codepoint pairs, while an encoding takes those codepoint numbers and \fIencodes\fR them, in our case into octets. Unicode is (among other things) a codeset, \s-1UTF\-8\s0 is an encoding, and \s-1ISO\-8859\-1\s0 (= latin 1) and \s-1ASCII\s0 are both codesets \fIand\fR encodings at the same time, which can be confusing. .ie n .IP """utf8"" flag disabled" 4 .el .IP "\f(CWutf8\fR flag disabled" 4 .IX Item "utf8 flag disabled" When \f(CW\*(C`utf8\*(C'\fR is disabled (the default), then \f(CW\*(C`encode\*(C'\fR/\f(CW\*(C`decode\*(C'\fR generate and expect Unicode strings, that is, characters with high ordinal Unicode values (> 255) will be encoded as such characters, and likewise such characters are decoded as-is, no changes to them will be done, except \&\*(L"(re\-)interpreting\*(R" them as Unicode codepoints or Unicode characters, respectively (to Perl, these are the same thing in strings unless you do funny/weird/dumb stuff). .Sp This is useful when you want to do the encoding yourself (e.g. when you want to have \s-1UTF\-16\s0 encoded \s-1JSON\s0 texts) or when some other layer does the encoding for you (for example, when printing to a terminal using a filehandle that transparently encodes to \s-1UTF\-8\s0 you certainly do \s-1NOT\s0 want to \s-1UTF\-8\s0 encode your data first and have Perl encode it another time). .ie n .IP """utf8"" flag enabled" 4 .el .IP "\f(CWutf8\fR flag enabled" 4 .IX Item "utf8 flag enabled" If the \f(CW\*(C`utf8\*(C'\fR\-flag is enabled, \f(CW\*(C`encode\*(C'\fR/\f(CW\*(C`decode\*(C'\fR will encode all characters using the corresponding \s-1UTF\-8\s0 multi-byte sequence, and will expect your input strings to be encoded as \s-1UTF\-8,\s0 that is, no \*(L"character\*(R" of the input string must have any value > 255, as \s-1UTF\-8\s0 does not allow that. .Sp The \f(CW\*(C`utf8\*(C'\fR flag therefore switches between two modes: disabled means you will get a Unicode string in Perl, enabled means you get a \s-1UTF\-8\s0 encoded octet/binary string in Perl. .ie n .IP """latin1"" or ""ascii"" flags enabled" 4 .el .IP "\f(CWlatin1\fR or \f(CWascii\fR flags enabled" 4 .IX Item "latin1 or ascii flags enabled" With \f(CW\*(C`latin1\*(C'\fR (or \f(CW\*(C`ascii\*(C'\fR) enabled, \f(CW\*(C`encode\*(C'\fR will escape characters with ordinal values > 255 (> 127 with \f(CW\*(C`ascii\*(C'\fR) and encode the remaining characters as specified by the \f(CW\*(C`utf8\*(C'\fR flag. .Sp If \f(CW\*(C`utf8\*(C'\fR is disabled, then the result is also correctly encoded in those character sets (as both are proper subsets of Unicode, meaning that a Unicode string with all character values < 256 is the same thing as a \&\s-1ISO\-8859\-1\s0 string, and a Unicode string with all character values < 128 is the same thing as an \s-1ASCII\s0 string in Perl). .Sp If \f(CW\*(C`utf8\*(C'\fR is enabled, you still get a correct UTF\-8\-encoded string, regardless of these flags, just some more characters will be escaped using \&\f(CW\*(C`\euXXXX\*(C'\fR then before. .Sp Note that \s-1ISO\-8859\-1\-\s0\fIencoded\fR strings are not compatible with \s-1UTF\-8\s0 encoding, while ASCII-encoded strings are. That is because the \s-1ISO\-8859\-1\s0 encoding is \s-1NOT\s0 a subset of \s-1UTF\-8\s0 (despite the \s-1ISO\-8859\-1\s0 \fIcodeset\fR being a subset of Unicode), while \s-1ASCII\s0 is. .Sp Surprisingly, \f(CW\*(C`decode\*(C'\fR will ignore these flags and so treat all input values as governed by the \f(CW\*(C`utf8\*(C'\fR flag. If it is disabled, this allows you to decode \s-1ISO\-8859\-1\-\s0 and ASCII-encoded strings, as both strict subsets of Unicode. If it is enabled, you can correctly decode \s-1UTF\-8\s0 encoded strings. .Sp So neither \f(CW\*(C`latin1\*(C'\fR nor \f(CW\*(C`ascii\*(C'\fR are incompatible with the \f(CW\*(C`utf8\*(C'\fR flag \- they only govern when the \s-1JSON\s0 output engine escapes a character or not. .Sp The main use for \f(CW\*(C`latin1\*(C'\fR is to relatively efficiently store binary data as \s-1JSON,\s0 at the expense of breaking compatibility with most \s-1JSON\s0 decoders. .Sp The main use for \f(CW\*(C`ascii\*(C'\fR is to force the output to not contain characters with values > 127, which means you can interpret the resulting string as \s-1UTF\-8, ISO\-8859\-1, ASCII, KOI8\-R\s0 or most about any character set and 8\-bit\-encoding, and still get the same data structure back. This is useful when your channel for \s-1JSON\s0 transfer is not 8\-bit clean or the encoding might be mangled in between (e.g. in mail), and works because \s-1ASCII\s0 is a proper subset of most 8\-bit and multibyte encodings in use in the world. .SS "\s-1JSON\s0 and ECMAscript" .IX Subsection "JSON and ECMAscript" \&\s-1JSON\s0 syntax is based on how literals are represented in javascript (the not-standardised predecessor of ECMAscript) which is presumably why it is called \*(L"JavaScript Object Notation\*(R". .PP However, \s-1JSON\s0 is not a subset (and also not a superset of course) of ECMAscript (the standard) or javascript (whatever browsers actually implement). .PP If you want to use javascript's \f(CW\*(C`eval\*(C'\fR function to \*(L"parse\*(R" \s-1JSON,\s0 you might run into parse errors for valid \s-1JSON\s0 texts, or the resulting data structure might not be queryable: .PP One of the problems is that U+2028 and U+2029 are valid characters inside \&\s-1JSON\s0 strings, but are not allowed in ECMAscript string literals, so the following Perl fragment will not output something that can be guaranteed to be parsable by javascript's \f(CW\*(C`eval\*(C'\fR: .PP .Vb 1 \& use JSON::XS; \& \& print encode_json [chr 0x2028]; .Ve .PP The right fix for this is to use a proper \s-1JSON\s0 parser in your javascript programs, and not rely on \f(CW\*(C`eval\*(C'\fR (see for example Douglas Crockford's \&\fIjson2.js\fR parser). .PP If this is not an option, you can, as a stop-gap measure, simply encode to ASCII-only \s-1JSON:\s0 .PP .Vb 1 \& use JSON::XS; \& \& print JSON::XS\->new\->ascii\->encode ([chr 0x2028]); .Ve .PP Note that this will enlarge the resulting \s-1JSON\s0 text quite a bit if you have many non-ASCII characters. You might be tempted to run some regexes to only escape U+2028 and U+2029, e.g.: .PP .Vb 5 \& # DO NOT USE THIS! \& my $json = JSON::XS\->new\->utf8\->encode ([chr 0x2028]); \& $json =~ s/\exe2\ex80\exa8/\e\eu2028/g; # escape U+2028 \& $json =~ s/\exe2\ex80\exa9/\e\eu2029/g; # escape U+2029 \& print $json; .Ve .PP Note that \fIthis is a bad idea\fR: the above only works for U+2028 and U+2029 and thus only for fully ECMAscript-compliant parsers. Many existing javascript implementations, however, have issues with other characters as well \- using \f(CW\*(C`eval\*(C'\fR naively simply \fIwill\fR cause problems. .PP Another problem is that some javascript implementations reserve some property names for their own purposes (which probably makes them non-ECMAscript-compliant). For example, Iceweasel reserves the \&\f(CW\*(C`_\|_proto_\|_\*(C'\fR property name for its own purposes. .PP If that is a problem, you could parse try to filter the resulting \s-1JSON\s0 output for these property strings, e.g.: .PP .Vb 1 \& $json =~ s/"_\|_proto_\|_"\es*:/"_\|_proto_\|_renamed":/g; .Ve .PP This works because \f(CW\*(C`_\|_proto_\|_\*(C'\fR is not valid outside of strings, so every occurrence of \f(CW\*(C`"_\|_proto_\|_"\es*:\*(C'\fR must be a string used as property name. .PP If you know of other incompatibilities, please let me know. .SS "\s-1JSON\s0 and \s-1YAML\s0" .IX Subsection "JSON and YAML" You often hear that \s-1JSON\s0 is a subset of \s-1YAML.\s0 This is, however, a mass hysteria(*) and very far from the truth (as of the time of this writing), so let me state it clearly: \fIin general, there is no way to configure \&\s-1JSON::XS\s0 to output a data structure as valid \s-1YAML\s0\fR that works in all cases. .PP If you really must use \s-1JSON::XS\s0 to generate \s-1YAML,\s0 you should use this algorithm (subject to change in future versions): .PP .Vb 2 \& my $to_yaml = JSON::XS\->new\->utf8\->space_after (1); \& my $yaml = $to_yaml\->encode ($ref) . "\en"; .Ve .PP This will \fIusually\fR generate \s-1JSON\s0 texts that also parse as valid \&\s-1YAML.\s0 Please note that \s-1YAML\s0 has hardcoded limits on (simple) object key lengths that \s-1JSON\s0 doesn't have and also has different and incompatible unicode character escape syntax, so you should make sure that your hash keys are noticeably shorter than the 1024 \*(L"stream characters\*(R" \s-1YAML\s0 allows and that you do not have characters with codepoint values outside the Unicode \s-1BMP\s0 (basic multilingual page). \s-1YAML\s0 also does not allow \f(CW\*(C`\e/\*(C'\fR sequences in strings (which \s-1JSON::XS\s0 does not \fIcurrently\fR generate, but other \s-1JSON\s0 generators might). .PP There might be other incompatibilities that I am not aware of (or the \s-1YAML\s0 specification has been changed yet again \- it does so quite often). In general you should not try to generate \s-1YAML\s0 with a \s-1JSON\s0 generator or vice versa, or try to parse \s-1JSON\s0 with a \s-1YAML\s0 parser or vice versa: chances are high that you will run into severe interoperability problems when you least expect it. .IP "(*)" 4 I have been pressured multiple times by Brian Ingerson (one of the authors of the \s-1YAML\s0 specification) to remove this paragraph, despite him acknowledging that the actual incompatibilities exist. As I was personally bitten by this \*(L"\s-1JSON\s0 is \s-1YAML\*(R"\s0 lie, I refused and said I will continue to educate people about these issues, so others do not run into the same problem again and again. After this, Brian called me a (quote)\fIcomplete and worthless idiot\fR(unquote). .Sp In my opinion, instead of pressuring and insulting people who actually clarify issues with \s-1YAML\s0 and the wrong statements of some of its proponents, I would kindly suggest reading the \s-1JSON\s0 spec (which is not that difficult or long) and finally make \s-1YAML\s0 compatible to it, and educating users about the changes, instead of spreading lies about the real compatibility for many \fIyears\fR and trying to silence people who point out that it isn't true. .Sp Addendum/2009: the \s-1YAML 1.2\s0 spec is still incompatible with \s-1JSON,\s0 even though the incompatibilities have been documented (and are known to Brian) for many years and the spec makes explicit claims that \s-1YAML\s0 is a superset of \s-1JSON.\s0 It would be so easy to fix, but apparently, bullying people and corrupting userdata is so much easier. .SS "\s-1SPEED\s0" .IX Subsection "SPEED" It seems that \s-1JSON::XS\s0 is surprisingly fast, as shown in the following tables. They have been generated with the help of the \f(CW\*(C`eg/bench\*(C'\fR program in the \s-1JSON::XS\s0 distribution, to make it easy to compare on your own system. .PP First comes a comparison between various modules using a very short single-line \s-1JSON\s0 string (also available at ). .PP .Vb 3 \& {"method": "handleMessage", "params": ["user1", \& "we were just talking"], "id": null, "array":[1,11,234,\-5,1e5,1e7, \& 1, 0]} .Ve .PP It shows the number of encodes/decodes per second (\s-1JSON::XS\s0 uses the functional interface, while \s-1JSON::XS/2\s0 uses the \s-1OO\s0 interface with pretty-printing and hashkey sorting enabled, \s-1JSON::XS/3\s0 enables shrink. \s-1JSON::DWIW/DS\s0 uses the deserialise function, while \s-1JSON::DWIW::FJ\s0 uses the from_json method). Higher is better: .PP .Vb 11 \& module | encode | decode | \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-| \& JSON::DWIW/DS | 86302.551 | 102300.098 | \& JSON::DWIW/FJ | 86302.551 | 75983.768 | \& JSON::PP | 15827.562 | 6638.658 | \& JSON::Syck | 63358.066 | 47662.545 | \& JSON::XS | 511500.488 | 511500.488 | \& JSON::XS/2 | 291271.111 | 388361.481 | \& JSON::XS/3 | 361577.931 | 361577.931 | \& Storable | 66788.280 | 265462.278 | \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+ .Ve .PP That is, \s-1JSON::XS\s0 is almost six times faster than \s-1JSON::DWIW\s0 on encoding, about five times faster on decoding, and over thirty to seventy times faster than \s-1JSON\s0's pure perl implementation. It also compares favourably to Storable for small amounts of data. .PP Using a longer test string (roughly 18KB, generated from Yahoo! Locals search \s-1API\s0 (). .PP .Vb 11 \& module | encode | decode | \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-| \& JSON::DWIW/DS | 1647.927 | 2673.916 | \& JSON::DWIW/FJ | 1630.249 | 2596.128 | \& JSON::PP | 400.640 | 62.311 | \& JSON::Syck | 1481.040 | 1524.869 | \& JSON::XS | 20661.596 | 9541.183 | \& JSON::XS/2 | 10683.403 | 9416.938 | \& JSON::XS/3 | 20661.596 | 9400.054 | \& Storable | 19765.806 | 10000.725 | \& \-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+ .Ve .PP Again, \s-1JSON::XS\s0 leads by far (except for Storable which non-surprisingly decodes a bit faster). .PP On large strings containing lots of high Unicode characters, some modules (such as \s-1JSON::PC\s0) seem to decode faster than \s-1JSON::XS,\s0 but the result will be broken due to missing (or wrong) Unicode handling. Others refuse to decode or encode properly, so it was impossible to prepare a fair comparison table for that case. .SH "SECURITY CONSIDERATIONS" .IX Header "SECURITY CONSIDERATIONS" When you are using \s-1JSON\s0 in a protocol, talking to untrusted potentially hostile creatures requires relatively few measures. .PP First of all, your \s-1JSON\s0 decoder should be secure, that is, should not have any buffer overflows. Obviously, this module should ensure that and I am trying hard on making that true, but you never know. .PP Second, you need to avoid resource-starving attacks. That means you should limit the size of \s-1JSON\s0 texts you accept, or make sure then when your resources run out, that's just fine (e.g. by using a separate process that can crash safely). The size of a \s-1JSON\s0 text in octets or characters is usually a good indication of the size of the resources required to decode it into a Perl structure. While \s-1JSON::XS\s0 can check the size of the \s-1JSON\s0 text, it might be too late when you already have it in memory, so you might want to check the size before you accept the string. .PP Third, \s-1JSON::XS\s0 recurses using the C stack when decoding objects and arrays. The C stack is a limited resource: for instance, on my amd64 machine with 8MB of stack size I can decode around 180k nested arrays but only 14k nested \s-1JSON\s0 objects (due to perl itself recursing deeply on croak to free the temporary). If that is exceeded, the program crashes. To be conservative, the default nesting limit is set to 512. If your process has a smaller stack, you should adjust this setting accordingly with the \&\f(CW\*(C`max_depth\*(C'\fR method. .PP Something else could bomb you, too, that I forgot to think of. In that case, you get to keep the pieces. I am always open for hints, though... .PP Also keep in mind that \s-1JSON::XS\s0 might leak contents of your Perl data structures in its error messages, so when you serialise sensitive information you might want to make sure that exceptions thrown by \s-1JSON::XS\s0 will not end up in front of untrusted eyes. .PP If you are using \s-1JSON::XS\s0 to return packets to consumption by JavaScript scripts in a browser you should have a look at to see whether you are vulnerable to some common attack vectors (which really are browser design bugs, but it is still you who will have to deal with it, as major browser developers care only for features, not about getting security right). .ie n .SS """\s-1OLD"" VS. ""NEW"" JSON\s0 (\s-1RFC4627 VS. RFC7159\s0)" .el .SS "``\s-1OLD'' VS. ``NEW'' JSON\s0 (\s-1RFC4627 VS. RFC7159\s0)" .IX Subsection "OLD VS. NEW JSON (RFC4627 VS. RFC7159)" \&\s-1JSON\s0 originally required \s-1JSON\s0 texts to represent an array or object \- scalar values were explicitly not allowed. This has changed, and versions of \s-1JSON::XS\s0 beginning with \f(CW4.0\fR reflect this by allowing scalar values by default. .PP One reason why one might not want this is that this removes a fundamental property of \s-1JSON\s0 texts, namely that they are self-delimited and self-contained, or in other words, you could take any number of \*(L"old\*(R" \&\s-1JSON\s0 texts and paste them together, and the result would be unambiguously parseable: .PP .Vb 1 \& [1,3]{"k":5}[][null] # four JSON texts, without doubt .Ve .PP By allowing scalars, this property is lost: in the following example, is this one \s-1JSON\s0 text (the number 12) or two \s-1JSON\s0 texts (the numbers 1 and 2): .PP .Vb 1 \& 12 # could be 12, or 1 and 2 .Ve .PP Another lost property of \*(L"old\*(R" \s-1JSON\s0 is that no lookahead is required to know the end of a \s-1JSON\s0 text, i.e. the \s-1JSON\s0 text definitely ended at the last \f(CW\*(C`]\*(C'\fR or \f(CW\*(C`}\*(C'\fR character, there was no need to read extra characters. .PP For example, a viable network protocol with \*(L"old\*(R" \s-1JSON\s0 was to simply exchange \s-1JSON\s0 texts without delimiter. For \*(L"new\*(R" \s-1JSON,\s0 you have to use a suitable delimiter (such as a newline) after every \s-1JSON\s0 text or ensure you never encode/decode scalar values. .PP Most protocols do work by only transferring arrays or objects, and the easiest way to avoid problems with the \*(L"new\*(R" \s-1JSON\s0 definition is to explicitly disallow scalar values in your encoder and decoder: .PP .Vb 1 \& $json_coder = JSON::XS\->new\->allow_nonref (0) .Ve .PP This is a somewhat unhappy situation, and the blame can fully be put on \&\s-1JSON\s0's inmventor, Douglas Crockford, who unilaterally changed the format in 2006 without consulting the \s-1IETF,\s0 forcing the \s-1IETF\s0 to either fork the format or go with it (as I was told, the \s-1IETF\s0 wasn't amused). .SH "RELATIONSHIP WITH I\-JSON" .IX Header "RELATIONSHIP WITH I-JSON" \&\s-1JSON\s0 is a somewhat sloppily-defined format \- it carries around obvious Javascript baggage, such as not really defining number range, probably because Javascript only has one type of numbers: \s-1IEEE 64\s0 bit floats (\*(L"binary64\*(R"). .PP For this reaosn, \s-1RFC7493\s0 defines \*(L"Internet \s-1JSON\*(R",\s0 which is a restricted subset of \s-1JSON\s0 that is supposedly more interoperable on the internet. .PP While \f(CW\*(C`JSON::XS\*(C'\fR does not offer specific support for I\-JSON, it of course accepts valid I\-JSON and by default implements some of the limitations of I\-JSON, such as parsing numbers as perl numbers, which are usually a superset of binary64 numbers. .PP To generate I\-JSON, follow these rules: .IP "\(bu" 4 always generate \s-1UTF\-8\s0 .Sp I\-JSON must be encoded in \s-1UTF\-8,\s0 the default for \f(CW\*(C`encode_json\*(C'\fR. .IP "\(bu" 4 numbers should be within \s-1IEEE 754\s0 binary64 range .Sp Basically all existing perl installations use binary64 to represent floating point numbers, so all you need to do is to avoid large integers. .IP "\(bu" 4 objects must not have duplicate keys .Sp This is trivially done, as \f(CW\*(C`JSON::XS\*(C'\fR does not allow duplicate keys. .IP "\(bu" 4 do not generate scalar \s-1JSON\s0 texts, use \f(CW\*(C`\->allow_nonref (0)\*(C'\fR .Sp I\-JSON strongly requests you to only encode arrays and objects into \s-1JSON.\s0 .IP "\(bu" 4 times should be strings in \s-1ISO 8601\s0 format .Sp There are a myriad of modules on \s-1CPAN\s0 dealing with \s-1ISO 8601\s0 \- search for \&\f(CW\*(C`ISO8601\*(C'\fR on \s-1CPAN\s0 and use one. .IP "\(bu" 4 encode binary data as base64 .Sp While it's tempting to just dump binary data as a string (and let \&\f(CW\*(C`JSON::XS\*(C'\fR do the escaping), for I\-JSON, it's \fIrecommended\fR to encode binary data as base64. .PP There are some other considerations \- read \s-1RFC7493\s0 for the details if interested. .SH "INTEROPERABILITY WITH OTHER MODULES" .IX Header "INTEROPERABILITY WITH OTHER MODULES" \&\f(CW\*(C`JSON::XS\*(C'\fR uses the Types::Serialiser module to provide boolean constants. That means that the \s-1JSON\s0 true and false values will be comaptible to true and false values of other modules that do the same, such as \s-1JSON::PP\s0 and \s-1CBOR::XS\s0. .SH "INTEROPERABILITY WITH OTHER JSON DECODERS" .IX Header "INTEROPERABILITY WITH OTHER JSON DECODERS" As long as you only serialise data that can be directly expressed in \s-1JSON,\s0 \&\f(CW\*(C`JSON::XS\*(C'\fR is incapable of generating invalid \s-1JSON\s0 output (modulo bugs, but \f(CW\*(C`JSON::XS\*(C'\fR has found more bugs in the official \s-1JSON\s0 testsuite (1) than the official \s-1JSON\s0 testsuite has found in \f(CW\*(C`JSON::XS\*(C'\fR (0)). .PP When you have trouble decoding \s-1JSON\s0 generated by this module using other decoders, then it is very likely that you have an encoding mismatch or the other decoder is broken. .PP When decoding, \f(CW\*(C`JSON::XS\*(C'\fR is strict by default and will likely catch all errors. There are currently two settings that change this: \f(CW\*(C`relaxed\*(C'\fR makes \f(CW\*(C`JSON::XS\*(C'\fR accept (but not generate) some non-standard extensions, and \f(CW\*(C`allow_tags\*(C'\fR will allow you to encode and decode Perl objects, at the cost of not outputting valid \s-1JSON\s0 anymore. .SS "\s-1TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS\s0" .IX Subsection "TAGGED VALUE SYNTAX AND STANDARD JSON EN/DECODERS" When you use \f(CW\*(C`allow_tags\*(C'\fR to use the extended (and also nonstandard and invalid) \s-1JSON\s0 syntax for serialised objects, and you still want to decode the generated When you want to serialise objects, you can run a regex to replace the tagged syntax by standard \s-1JSON\s0 arrays (it only works for \&\*(L"normal\*(R" package names without comma, newlines or single colons). First, the readable Perl version: .PP .Vb 2 \& # if your FREEZE methods return no values, you need this replace first: \& $json =~ s/\e( \es* (" (?: [^\e\e":,]+|\e\e.|::)* ") \es* \e) \es* \e[\es*\e]/[$1]/gx; \& \& # this works for non\-empty constructor arg lists: \& $json =~ s/\e( \es* (" (?: [^\e\e":,]+|\e\e.|::)* ") \es* \e) \es* \e[/[$1,/gx; .Ve .PP And here is a less readable version that is easy to adapt to other languages: .PP .Vb 1 \& $json =~ s/\e(\es*("([^\e\e":,]+|\e\e.|::)*")\es*\e)\es*\e[/[$1,/g; .Ve .PP Here is an ECMAScript version (same regex): .PP .Vb 1 \& json = json.replace (/\e(\es*("([^\e\e":,]+|\e\e.|::)*")\es*\e)\es*\e[/g, "[$1,"); .Ve .PP Since this syntax converts to standard \s-1JSON\s0 arrays, it might be hard to distinguish serialised objects from normal arrays. You can prepend a \&\*(L"magic number\*(R" as first array element to reduce chances of a collision: .PP .Vb 1 \& $json =~ s/\e(\es*("([^\e\e":,]+|\e\e.|::)*")\es*\e)\es*\e[/["XU1peReLzT4ggEllLanBYq4G9VzliwKF",$1,/g; .Ve .PP And after decoding the \s-1JSON\s0 text, you could walk the data structure looking for arrays with a first element of \&\f(CW\*(C`XU1peReLzT4ggEllLanBYq4G9VzliwKF\*(C'\fR. .PP The same approach can be used to create the tagged format with another encoder. First, you create an array with the magic string as first member, the classname as second, and constructor arguments last, encode it as part of your \s-1JSON\s0 structure, and then: .PP .Vb 1 \& $json =~ s/\e[\es*"XU1peReLzT4ggEllLanBYq4G9VzliwKF"\es*,\es*("([^\e\e":,]+|\e\e.|::)*")\es*,/($1)[/g; .Ve .PP Again, this has some limitations \- the magic string must not be encoded with character escapes, and the constructor arguments must be non-empty. .SH "(I\-)THREADS" .IX Header "(I-)THREADS" This module is \fInot\fR guaranteed to be ithread (or \s-1MULTIPLICITY\-\s0) safe and there are no plans to change this. Note that perl's builtin so-called threads/ithreads are officially deprecated and should not be used. .SH "THE PERILS OF SETLOCALE" .IX Header "THE PERILS OF SETLOCALE" Sometimes people avoid the Perl locale support and directly call the system's setlocale function with \f(CW\*(C`LC_ALL\*(C'\fR. .PP This breaks both perl and modules such as \s-1JSON::XS,\s0 as stringification of numbers no longer works correctly (e.g. \f(CW\*(C`$x = 0.1; print "$x"+1\*(C'\fR might print \f(CW1\fR, and \s-1JSON::XS\s0 might output illegal \s-1JSON\s0 as \s-1JSON::XS\s0 relies on perl to stringify numbers). .PP The solution is simple: don't call \f(CW\*(C`setlocale\*(C'\fR, or use it for only those categories you need, such as \f(CW\*(C`LC_MESSAGES\*(C'\fR or \f(CW\*(C`LC_CTYPE\*(C'\fR. .PP If you need \f(CW\*(C`LC_NUMERIC\*(C'\fR, you should enable it only around the code that actually needs it (avoiding stringification of numbers), and restore it afterwards. .SH "SOME HISTORY" .IX Header "SOME HISTORY" At the time this module was created there already were a number of \s-1JSON\s0 modules available on \s-1CPAN,\s0 so what was the reason to write yet another \&\s-1JSON\s0 module? While it seems there are many \s-1JSON\s0 modules, none of them correctly handled all corner cases, and in most cases their maintainers are unresponsive, gone missing, or not listening to bug reports for other reasons. .PP Beginning with version 2.0 of the \s-1JSON\s0 module, when both \s-1JSON\s0 and \&\s-1JSON::XS\s0 are installed, then \s-1JSON\s0 will fall back on \s-1JSON::XS\s0 (this can be overridden) with no overhead due to emulation (by inheriting constructor and methods). If \s-1JSON::XS\s0 is not available, it will fall back to the compatible \s-1JSON::PP\s0 module as backend, so using \s-1JSON\s0 instead of \s-1JSON::XS\s0 gives you a portable \s-1JSON API\s0 that can be fast when you need it and doesn't require a C compiler when that is a problem. .PP Somewhere around version 3, this module was forked into \&\f(CW\*(C`Cpanel::JSON::XS\*(C'\fR, because its maintainer had serious trouble understanding \s-1JSON\s0 and insisted on a fork with many bugs \*(L"fixed\*(R" that weren't actually bugs, while spreading \s-1FUD\s0 about this module without actually giving any details on his accusations. You be the judge, but in my personal opinion, if you want quality, you will stay away from dangerous forks like that. .SH "BUGS" .IX Header "BUGS" While the goal of this module is to be correct, that unfortunately does not mean it's bug-free, only that I think its design is bug-free. If you keep reporting bugs they will be fixed swiftly, though. .PP Please refrain from using rt.cpan.org or any other bug reporting service. I put the contact address into my modules for a reason. .SH "SEE ALSO" .IX Header "SEE ALSO" The \fIjson_xs\fR command line utility for quick experiments. .SH "AUTHOR" .IX Header "AUTHOR" .Vb 2 \& Marc Lehmann \& http://home.schmorp.de/ .Ve PK@O\%%IO::Tty::Constant.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Tty::Constant 3" .TH Tty::Constant 3 "2024-03-13" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" IO::Tty::Constant \- Terminal Constants (autogenerated) .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use IO::Tty::Constant qw(TIOCNOTTY); \& ... .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This package defines constants usually found in or (and their #include hierarchy). Find below an autogenerated alphabetic list of all known constants and whether they are defined on your system (prefixed with '+') and have compilation problems ('o'). Undefined or problematic constants are set to 'undef'. .SH "DEFINED CONSTANTS" .IX Header "DEFINED CONSTANTS" .IP "+" 4 B0 .IP "+" 4 B110 .IP "+" 4 B115200 .IP "+" 4 B1200 .IP "+" 4 B134 .IP "+" 4 B150 .IP "\-" 4 B153600 .IP "+" 4 B1800 .IP "+" 4 B19200 .IP "+" 4 B200 .IP "+" 4 B230400 .IP "+" 4 B2400 .IP "+" 4 B300 .IP "\-" 4 B307200 .IP "+" 4 B38400 .IP "+" 4 B460800 .IP "+" 4 B4800 .IP "+" 4 B50 .IP "+" 4 B57600 .IP "+" 4 B600 .IP "+" 4 B75 .IP "\-" 4 B76800 .IP "+" 4 B9600 .IP "+" 4 \&\s-1BRKINT\s0 .IP "+" 4 \&\s-1BS0\s0 .IP "+" 4 \&\s-1BS1\s0 .IP "+" 4 \&\s-1BSDLY\s0 .IP "+" 4 \&\s-1CBAUD\s0 .IP "\-" 4 \&\s-1CBAUDEXT\s0 .IP "+" 4 \&\s-1CBRK\s0 .IP "\-" 4 \&\s-1CCTS_OFLOW\s0 .IP "\-" 4 \&\s-1CDEL\s0 .IP "+" 4 \&\s-1CDSUSP\s0 .IP "+" 4 \&\s-1CEOF\s0 .IP "+" 4 \&\s-1CEOL\s0 .IP "\-" 4 \&\s-1CEOL2\s0 .IP "+" 4 \&\s-1CEOT\s0 .IP "+" 4 \&\s-1CERASE\s0 .IP "\-" 4 \&\s-1CESC\s0 .IP "+" 4 \&\s-1CFLUSH\s0 .IP "+" 4 \&\s-1CIBAUD\s0 .IP "\-" 4 \&\s-1CIBAUDEXT\s0 .IP "+" 4 \&\s-1CINTR\s0 .IP "+" 4 \&\s-1CKILL\s0 .IP "+" 4 \&\s-1CLNEXT\s0 .IP "+" 4 \&\s-1CLOCAL\s0 .IP "\-" 4 \&\s-1CNSWTCH\s0 .IP "\-" 4 \&\s-1CNUL\s0 .IP "+" 4 \&\s-1CQUIT\s0 .IP "+" 4 \&\s-1CR0\s0 .IP "+" 4 \&\s-1CR1\s0 .IP "+" 4 \&\s-1CR2\s0 .IP "+" 4 \&\s-1CR3\s0 .IP "+" 4 \&\s-1CRDLY\s0 .IP "+" 4 \&\s-1CREAD\s0 .IP "+" 4 \&\s-1CRPRNT\s0 .IP "+" 4 \&\s-1CRTSCTS\s0 .IP "\-" 4 \&\s-1CRTSXOFF\s0 .IP "\-" 4 \&\s-1CRTS_IFLOW\s0 .IP "+" 4 \&\s-1CS5\s0 .IP "+" 4 \&\s-1CS6\s0 .IP "+" 4 \&\s-1CS7\s0 .IP "+" 4 \&\s-1CS8\s0 .IP "+" 4 \&\s-1CSIZE\s0 .IP "+" 4 \&\s-1CSTART\s0 .IP "+" 4 \&\s-1CSTOP\s0 .IP "+" 4 \&\s-1CSTOPB\s0 .IP "+" 4 \&\s-1CSUSP\s0 .IP "\-" 4 \&\s-1CSWTCH\s0 .IP "+" 4 \&\s-1CWERASE\s0 .IP "\-" 4 \&\s-1DEFECHO\s0 .IP "\-" 4 \&\s-1DIOC\s0 .IP "\-" 4 \&\s-1DIOCGETP\s0 .IP "\-" 4 \&\s-1DIOCSETP\s0 .IP "\-" 4 \&\s-1DOSMODE\s0 .IP "+" 4 \&\s-1ECHO\s0 .IP "+" 4 \&\s-1ECHOCTL\s0 .IP "+" 4 \&\s-1ECHOE\s0 .IP "+" 4 \&\s-1ECHOK\s0 .IP "+" 4 \&\s-1ECHOKE\s0 .IP "+" 4 \&\s-1ECHONL\s0 .IP "+" 4 \&\s-1ECHOPRT\s0 .IP "+" 4 \&\s-1EXTA\s0 .IP "+" 4 \&\s-1EXTB\s0 .IP "+" 4 \&\s-1FF0\s0 .IP "+" 4 \&\s-1FF1\s0 .IP "+" 4 \&\s-1FFDLY\s0 .IP "\-" 4 \&\s-1FIORDCHK\s0 .IP "+" 4 \&\s-1FLUSHO\s0 .IP "+" 4 \&\s-1HUPCL\s0 .IP "+" 4 \&\s-1ICANON\s0 .IP "+" 4 \&\s-1ICRNL\s0 .IP "+" 4 \&\s-1IEXTEN\s0 .IP "+" 4 \&\s-1IGNBRK\s0 .IP "+" 4 \&\s-1IGNCR\s0 .IP "+" 4 \&\s-1IGNPAR\s0 .IP "+" 4 \&\s-1IMAXBEL\s0 .IP "+" 4 \&\s-1INLCR\s0 .IP "+" 4 \&\s-1INPCK\s0 .IP "+" 4 \&\s-1ISIG\s0 .IP "+" 4 \&\s-1ISTRIP\s0 .IP "+" 4 \&\s-1IUCLC\s0 .IP "+" 4 \&\s-1IXANY\s0 .IP "+" 4 \&\s-1IXOFF\s0 .IP "+" 4 \&\s-1IXON\s0 .IP "\-" 4 \&\s-1KBENABLED\s0 .IP "\-" 4 \&\s-1LDCHG\s0 .IP "\-" 4 \&\s-1LDCLOSE\s0 .IP "\-" 4 \&\s-1LDDMAP\s0 .IP "\-" 4 \&\s-1LDEMAP\s0 .IP "\-" 4 \&\s-1LDGETT\s0 .IP "\-" 4 \&\s-1LDGMAP\s0 .IP "\-" 4 \&\s-1LDIOC\s0 .IP "\-" 4 \&\s-1LDNMAP\s0 .IP "\-" 4 \&\s-1LDOPEN\s0 .IP "\-" 4 \&\s-1LDSETT\s0 .IP "\-" 4 \&\s-1LDSMAP\s0 .IP "\-" 4 \&\s-1LOBLK\s0 .IP "+" 4 \&\s-1NCCS\s0 .IP "+" 4 \&\s-1NL0\s0 .IP "+" 4 \&\s-1NL1\s0 .IP "+" 4 \&\s-1NLDLY\s0 .IP "+" 4 \&\s-1NOFLSH\s0 .IP "+" 4 \&\s-1OCRNL\s0 .IP "+" 4 \&\s-1OFDEL\s0 .IP "+" 4 \&\s-1OFILL\s0 .IP "+" 4 \&\s-1OLCUC\s0 .IP "+" 4 \&\s-1ONLCR\s0 .IP "+" 4 \&\s-1ONLRET\s0 .IP "+" 4 \&\s-1ONOCR\s0 .IP "+" 4 \&\s-1OPOST\s0 .IP "\-" 4 \&\s-1PAGEOUT\s0 .IP "+" 4 \&\s-1PARENB\s0 .IP "\-" 4 \&\s-1PAREXT\s0 .IP "+" 4 \&\s-1PARMRK\s0 .IP "+" 4 \&\s-1PARODD\s0 .IP "+" 4 \&\s-1PENDIN\s0 .IP "\-" 4 \&\s-1RCV1EN\s0 .IP "\-" 4 \&\s-1RTS_TOG\s0 .IP "+" 4 \&\s-1TAB0\s0 .IP "+" 4 \&\s-1TAB1\s0 .IP "+" 4 \&\s-1TAB2\s0 .IP "+" 4 \&\s-1TAB3\s0 .IP "+" 4 \&\s-1TABDLY\s0 .IP "\-" 4 \&\s-1TCDSET\s0 .IP "+" 4 \&\s-1TCFLSH\s0 .IP "+" 4 \&\s-1TCGETA\s0 .IP "+" 4 \&\s-1TCGETS\s0 .IP "+" 4 \&\s-1TCIFLUSH\s0 .IP "+" 4 \&\s-1TCIOFF\s0 .IP "+" 4 \&\s-1TCIOFLUSH\s0 .IP "+" 4 \&\s-1TCION\s0 .IP "+" 4 \&\s-1TCOFLUSH\s0 .IP "+" 4 \&\s-1TCOOFF\s0 .IP "+" 4 \&\s-1TCOON\s0 .IP "+" 4 \&\s-1TCSADRAIN\s0 .IP "+" 4 \&\s-1TCSAFLUSH\s0 .IP "+" 4 \&\s-1TCSANOW\s0 .IP "+" 4 \&\s-1TCSBRK\s0 .IP "+" 4 \&\s-1TCSETA\s0 .IP "+" 4 \&\s-1TCSETAF\s0 .IP "+" 4 \&\s-1TCSETAW\s0 .IP "\-" 4 \&\s-1TCSETCTTY\s0 .IP "+" 4 \&\s-1TCSETS\s0 .IP "+" 4 \&\s-1TCSETSF\s0 .IP "+" 4 \&\s-1TCSETSW\s0 .IP "+" 4 \&\s-1TCXONC\s0 .IP "\-" 4 \&\s-1TERM_D40\s0 .IP "\-" 4 \&\s-1TERM_D42\s0 .IP "\-" 4 \&\s-1TERM_H45\s0 .IP "\-" 4 \&\s-1TERM_NONE\s0 .IP "\-" 4 \&\s-1TERM_TEC\s0 .IP "\-" 4 \&\s-1TERM_TEX\s0 .IP "\-" 4 \&\s-1TERM_V10\s0 .IP "\-" 4 \&\s-1TERM_V61\s0 .IP "+" 4 \&\s-1TIOCCBRK\s0 .IP "\-" 4 \&\s-1TIOCCDTR\s0 .IP "+" 4 \&\s-1TIOCCONS\s0 .IP "+" 4 \&\s-1TIOCEXCL\s0 .IP "\-" 4 \&\s-1TIOCFLUSH\s0 .IP "+" 4 \&\s-1TIOCGETD\s0 .IP "\-" 4 \&\s-1TIOCGETC\s0 .IP "\-" 4 \&\s-1TIOCGETP\s0 .IP "\-" 4 \&\s-1TIOCGLTC\s0 .IP "\-" 4 \&\s-1TIOCSETC\s0 .IP "\-" 4 \&\s-1TIOCSETN\s0 .IP "\-" 4 \&\s-1TIOCSETP\s0 .IP "\-" 4 \&\s-1TIOCSLTC\s0 .IP "+" 4 \&\s-1TIOCGPGRP\s0 .IP "+" 4 \&\s-1TIOCGSID\s0 .IP "+" 4 \&\s-1TIOCGSOFTCAR\s0 .IP "+" 4 \&\s-1TIOCGWINSZ\s0 .IP "\-" 4 \&\s-1TIOCHPCL\s0 .IP "\-" 4 \&\s-1TIOCKBOF\s0 .IP "\-" 4 \&\s-1TIOCKBON\s0 .IP "\-" 4 \&\s-1TIOCLBIC\s0 .IP "\-" 4 \&\s-1TIOCLBIS\s0 .IP "\-" 4 \&\s-1TIOCLGET\s0 .IP "\-" 4 \&\s-1TIOCLSET\s0 .IP "+" 4 \&\s-1TIOCMBIC\s0 .IP "+" 4 \&\s-1TIOCMBIS\s0 .IP "+" 4 \&\s-1TIOCMGET\s0 .IP "+" 4 \&\s-1TIOCMSET\s0 .IP "+" 4 \&\s-1TIOCM_CAR\s0 .IP "+" 4 \&\s-1TIOCM_CD\s0 .IP "+" 4 \&\s-1TIOCM_CTS\s0 .IP "+" 4 \&\s-1TIOCM_DSR\s0 .IP "+" 4 \&\s-1TIOCM_DTR\s0 .IP "+" 4 \&\s-1TIOCM_LE\s0 .IP "+" 4 \&\s-1TIOCM_RI\s0 .IP "+" 4 \&\s-1TIOCM_RNG\s0 .IP "+" 4 \&\s-1TIOCM_RTS\s0 .IP "+" 4 \&\s-1TIOCM_SR\s0 .IP "+" 4 \&\s-1TIOCM_ST\s0 .IP "+" 4 \&\s-1TIOCNOTTY\s0 .IP "+" 4 \&\s-1TIOCNXCL\s0 .IP "+" 4 \&\s-1TIOCOUTQ\s0 .IP "\-" 4 \&\s-1TIOCREMOTE\s0 .IP "+" 4 \&\s-1TIOCSBRK\s0 .IP "+" 4 \&\s-1TIOCSCTTY\s0 .IP "\-" 4 \&\s-1TIOCSDTR\s0 .IP "+" 4 \&\s-1TIOCSETD\s0 .IP "\-" 4 \&\s-1TIOCSIGNAL\s0 .IP "+" 4 \&\s-1TIOCSPGRP\s0 .IP "\-" 4 \&\s-1TIOCSSID\s0 .IP "+" 4 \&\s-1TIOCSSOFTCAR\s0 .IP "\-" 4 \&\s-1TIOCSTART\s0 .IP "+" 4 \&\s-1TIOCSTI\s0 .IP "\-" 4 \&\s-1TIOCSTOP\s0 .IP "+" 4 \&\s-1TIOCSWINSZ\s0 .IP "\-" 4 \&\s-1TM_ANL\s0 .IP "\-" 4 \&\s-1TM_CECHO\s0 .IP "\-" 4 \&\s-1TM_CINVIS\s0 .IP "\-" 4 \&\s-1TM_LCF\s0 .IP "\-" 4 \&\s-1TM_NONE\s0 .IP "\-" 4 \&\s-1TM_SET\s0 .IP "\-" 4 \&\s-1TM_SNL\s0 .IP "+" 4 \&\s-1TOSTOP\s0 .IP "\-" 4 \&\s-1VCEOF\s0 .IP "\-" 4 \&\s-1VCEOL\s0 .IP "+" 4 \&\s-1VDISCARD\s0 .IP "\-" 4 \&\s-1VDSUSP\s0 .IP "+" 4 \&\s-1VEOF\s0 .IP "+" 4 \&\s-1VEOL\s0 .IP "+" 4 \&\s-1VEOL2\s0 .IP "+" 4 \&\s-1VERASE\s0 .IP "+" 4 \&\s-1VINTR\s0 .IP "+" 4 \&\s-1VKILL\s0 .IP "+" 4 \&\s-1VLNEXT\s0 .IP "+" 4 \&\s-1VMIN\s0 .IP "+" 4 \&\s-1VQUIT\s0 .IP "+" 4 \&\s-1VREPRINT\s0 .IP "+" 4 \&\s-1VSTART\s0 .IP "+" 4 \&\s-1VSTOP\s0 .IP "+" 4 \&\s-1VSUSP\s0 .IP "\-" 4 \&\s-1VSWTCH\s0 .IP "+" 4 \&\s-1VT0\s0 .IP "+" 4 \&\s-1VT1\s0 .IP "+" 4 \&\s-1VTDLY\s0 .IP "+" 4 \&\s-1VTIME\s0 .IP "+" 4 \&\s-1VWERASE\s0 .IP "\-" 4 \&\s-1WRAP\s0 .IP "+" 4 \&\s-1XCASE\s0 .IP "\-" 4 \&\s-1XCLUDE\s0 .IP "\-" 4 \&\s-1XMT1EN\s0 .IP "+" 4 \&\s-1XTABS\s0 .SH "FOR MORE INFO SEE" .IX Header "FOR MORE INFO SEE" IO::Tty PK@O\j, CPAN::HandleConfig.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::HandleConfig 3" .TH CPAN::HandleConfig 3 "2022-04-03" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::HandleConfig \- internal configuration handling for CPAN.pm .ie n .SS """CLASS\->safe_quote ITEM""" .el .SS "\f(CWCLASS\->safe_quote ITEM\fP" .IX Subsection "CLASS->safe_quote ITEM" Quotes an item to become safe against spaces in shell interpolation. An item is enclosed in double quotes if: .PP .Vb 2 \& \- the item contains spaces in the middle \& \- the item does not start with a quote .Ve .PP This happens to avoid shell interpolation problems when whitespace is present in directory names. .PP This method uses \f(CW\*(C`commands_quote\*(C'\fR to determine the correct quote. If \f(CW\*(C`commands_quote\*(C'\fR is a space, no quoting will take place. .PP if it starts and ends with the same quote character: leave it as it is .PP if it contains no whitespace: leave it as it is .PP if it contains whitespace, then .PP if it contains quotes: better leave it as it is .PP else: quote it with the correct quote type for the box we're on .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK@O\LL Expect.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Expect 3" .TH Expect 3 "2024-03-08" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Expect \- automate interactions with command line programs that expose a text terminal interface. .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Expect; \& \& # create an Expect object by spawning another process \& my $exp = Expect\->spawn($command, @params) \& or die "Cannot spawn $command: $!\en"; \& \& # or by using an already opened filehandle (e.g. from Net::Telnet) \& my $exp = Expect\->exp_init(\e*FILEHANDLE); \& \& # if you prefer the OO mindset: \& my $exp = Expect\->new; \& $exp\->raw_pty(1); \& $exp\->spawn($command, @parameters) \& or die "Cannot spawn $command: $!\en"; \& \& # send some string there: \& $exp\->send("string\en"); \& \& # or, for the filehandle mindset: \& print $exp "string\en"; \& \& # then do some pattern matching with either the simple interface \& $patidx = $exp\->expect($timeout, @match_patterns); \& \& # or multi\-match on several spawned commands with callbacks, \& # just like the Tcl version \& $exp\->expect($timeout, \& [ qr/regex1/ => sub { my $exp = shift; \& $exp\->send("response\en"); \& exp_continue; } ], \& [ "regexp2" , \e&callback, @cbparms ], \& ); \& \& # if no longer needed, do a soft_close to nicely shut down the command \& $exp\->soft_close(); \& \& # or be less patient with \& $exp\->hard_close(); .Ve .PP Expect.pm is built to either spawn a process or take an existing filehandle and interact with it such that normally interactive tasks can be done without operator assistance. This concept makes more sense if you are already familiar with the versatile Tcl version of Expect. The public functions that make up Expect.pm are: .PP .Vb 10 \& Expect\->new() \& Expect::interconnect(@objects_to_be_read_from) \& Expect::test_handles($timeout, @objects_to_test) \& Expect::version($version_requested | undef); \& $object\->spawn(@command) \& $object\->clear_accum() \& $object\->set_accum($value) \& $object\->debug($debug_level) \& $object\->exp_internal(0 | 1) \& $object\->notransfer(0 | 1) \& $object\->raw_pty(0 | 1) \& $object\->stty(@stty_modes) # See the IO::Stty docs \& $object\->slave() \& $object\->before(); \& $object\->match(); \& $object\->after(); \& $object\->matchlist(); \& $object\->match_number(); \& $object\->error(); \& $object\->command(); \& $object\->exitstatus(); \& $object\->pty_handle(); \& $object\->do_soft_close(); \& $object\->restart_timeout_upon_receive(0 | 1); \& $object\->interact($other_object, $escape_sequence) \& $object\->log_group(0 | 1 | undef) \& $object\->log_user(0 | 1 | undef) \& $object\->log_file("filename" | $filehandle | \e&coderef | undef) \& $object\->manual_stty(0 | 1 | undef) \& $object\->match_max($max_buffersize or undef) \& $object\->pid(); \& $object\->send_slow($delay, @strings_to_send) \& $object\->set_group(@listen_group_objects | undef) \& $object\->set_seq($sequence,\e&function,\e@parameters); .Ve .PP There are several configurable package variables that affect the behavior of Expect. They are: .PP .Vb 8 \& $Expect::Debug; \& $Expect::Exp_Internal; \& $Expect::IgnoreEintr; \& $Expect::Log_Group; \& $Expect::Log_Stdout; \& $Expect::Manual_Stty; \& $Expect::Multiline_Matching; \& $Expect::Do_Soft_Close; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" See an explanation of What is Expect .PP The Expect module is a successor of Comm.pl and a descendent of Chat.pl. It more closely resembles the Tcl Expect language than its predecessors. It does not contain any of the networking code found in Comm.pl. I suspect this would be obsolete anyway given the advent of IO::Socket and external tools such as netcat. .PP Expect.pm is an attempt to have more of a \fBswitch()\fR & case feeling to make decision processing more fluid. Three separate types of debugging have been implemented to make code production easier. .PP It is possible to interconnect multiple file handles (and processes) much like Tcl's Expect. An attempt was made to enable all the features of Tcl's Expect without forcing Tcl on the victim programmer :\-) . .PP Please, before you consider using Expect, read the FAQs about \&\*(L"I want to automate password entry for su/ssh/scp/rsh/...\*(R" and \&\*(L"I want to use Expect to automate [anything with a buzzword]...\*(R" .SH "USAGE" .IX Header "USAGE" .IP "new" 4 .IX Item "new" Creates a new Expect object, i.e. a pty. You can change parameters on it before actually spawning a command. This is important if you want to modify the terminal settings for the slave. See \fBslave()\fR below. The object returned is actually a reblessed IO::Pty filehandle, so see there for additional methods. .IP "Expect\->exp_init(\e*FILEHANDLE) \fIor\fR" 4 .IX Item "Expect->exp_init(*FILEHANDLE) or" .PD 0 .IP "Expect\->init(\e*FILEHANDLE)" 4 .IX Item "Expect->init(*FILEHANDLE)" .PD Initializes \f(CW$new_handle_object\fR for use with other Expect functions. It must be passed a \fB_reference_\fR to \s-1FILEHANDLE\s0 if you want it to work properly. IO::File objects are preferable. Returns a reference to the newly created object. .Sp You can use only real filehandles, certain tied filehandles (e.g. Net::SSH2) that lack a \fBfileno()\fR will not work. Net::Telnet objects can be used but have been reported to work only for certain hosts. \s-1YMMV.\s0 .ie n .IP "Expect\->spawn($command, @parameters) \fIor\fR" 4 .el .IP "Expect\->spawn($command, \f(CW@parameters\fR) \fIor\fR" 4 .IX Item "Expect->spawn($command, @parameters) or" .PD 0 .ie n .IP "$object\->spawn($command, @parameters) \fIor\fR" 4 .el .IP "\f(CW$object\fR\->spawn($command, \f(CW@parameters\fR) \fIor\fR" 4 .IX Item "$object->spawn($command, @parameters) or" .ie n .IP "Expect\->new($command, @parameters)" 4 .el .IP "Expect\->new($command, \f(CW@parameters\fR)" 4 .IX Item "Expect->new($command, @parameters)" .PD Forks and execs \f(CW$command\fR. Returns an Expect object upon success or \&\f(CW\*(C`undef\*(C'\fR if the fork was unsuccessful or the command could not be found. \fBspawn()\fR passes its parameters unchanged to Perls \fBexec()\fR, so look there for detailed semantics. .Sp Note that if spawn cannot \fBexec()\fR the given command, the Expect object is still valid and the next \fBexpect()\fR will see \*(L"Cannot exec\*(R", so you can use that for error handling. .Sp Also note that you cannot reuse an object with an already spawned command, even if that command has exited. Sorry, but you have to allocate a new object... .ie n .IP "$object\->debug(0 | 1 | 2 | 3 | undef)" 4 .el .IP "\f(CW$object\fR\->debug(0 | 1 | 2 | 3 | undef)" 4 .IX Item "$object->debug(0 | 1 | 2 | 3 | undef)" Sets debug level for \f(CW$object\fR. 1 refers to general debugging information, 2 refers to verbose debugging and 0 refers to no debugging. If you call \fBdebug()\fR with no parameters it will return the current debugging level. When the object is created the debugging level will match that \f(CW$Expect::Debug\fR, normally 0. .Sp The '3' setting is new with 1.05, and adds the additional functionality of having the _full_ accumulated buffer printed every time data is read from an Expect object. This was implemented by request. I recommend against using this unless you think you need it as it can create quite a quantity of output under some circumstances.. .ie n .IP "$object\->exp_internal(1 | 0)" 4 .el .IP "\f(CW$object\fR\->exp_internal(1 | 0)" 4 .IX Item "$object->exp_internal(1 | 0)" Sets/unsets 'exp_internal' debugging. This is similar in nature to its Tcl counterpart. It is extremely valuable when debugging \fBexpect()\fR sequences. When the object is created the exp_internal setting will match the value of \&\f(CW$Expect::Exp_Internal\fR, normally 0. Returns the current setting if called without parameters. It is highly recommended that you make use of the debugging features lest you have angry code. .ie n .IP "$object\->raw_pty(1 | 0)" 4 .el .IP "\f(CW$object\fR\->raw_pty(1 | 0)" 4 .IX Item "$object->raw_pty(1 | 0)" Set pty to raw mode before spawning. This disables echoing, \s-1CR\-\s0>\s-1LF\s0 translation and an ugly hack for broken Solaris TTYs (which send to slow things down) and thus gives a more pipe-like behaviour (which is important if you want to transfer binary content). Note that this must be set \fIbefore\fR spawning the program. .ie n .IP "$object\->stty(qw(mode1 mode2...))" 4 .el .IP "\f(CW$object\fR\->stty(qw(mode1 mode2...))" 4 .IX Item "$object->stty(qw(mode1 mode2...))" Sets the tty mode for \f(CW$object\fR's associated terminal to the given modes. Note that on many systems the master side of the pty is not a tty, so you have to modify the slave pty instead, see next item. This needs IO::Stty installed, which is no longer required. .ie n .IP "$object\->\fBslave()\fR" 4 .el .IP "\f(CW$object\fR\->\fBslave()\fR" 4 .IX Item "$object->slave()" Returns a filehandle to the slave part of the pty. Very useful in modifying the terminal settings: .Sp .Vb 1 \& $object\->slave\->stty(qw(raw \-echo)); .Ve .Sp Typical values are 'sane', 'raw', and 'raw \-echo'. Note that I recommend setting the terminal to 'raw' or 'raw \-echo', as this avoids a lot of hassle and gives pipe-like (i.e. transparent) behaviour (without the buffering issue). .ie n .IP "$object\->print(@strings) \fIor\fR" 4 .el .IP "\f(CW$object\fR\->print(@strings) \fIor\fR" 4 .IX Item "$object->print(@strings) or" .PD 0 .ie n .IP "$object\->send(@strings)" 4 .el .IP "\f(CW$object\fR\->send(@strings)" 4 .IX Item "$object->send(@strings)" .PD Sends the given strings to the spawned command. Note that the strings are not logged in the logfile (see print_log_file) but will probably be echoed back by the pty, depending on pty settings (default is echo) and thus end up there anyway. This must also be taken into account when \fBexpect()\fRing for an answer: the next string will be the command just sent. I suggest setting the pty to raw, which disables echo and makes the pty transparently act like a bidirectional pipe. .ie n .IP "$object\->expect($timeout, @match_patterns)" 4 .el .IP "\f(CW$object\fR\->expect($timeout, \f(CW@match_patterns\fR)" 4 .IX Item "$object->expect($timeout, @match_patterns)" .RS 4 .PD 0 .IP "Simple interface" 4 .IX Item "Simple interface" .PD Given \f(CW$timeout\fR in seconds Expect will wait for \f(CW$object\fR's handle to produce one of the match_patterns, which are matched exactly by default. If you want a regexp match, use a regexp object (\f(CW\*(C`qr//\*(C'\fR) or prefix the pattern with '\-re'. .Sp .Vb 2 \& $object\->expect(15, \*(Aqmatch me exactly\*(Aq, qr/match\es+me\es+exactly/); \& $object\->expect(15, \*(Aqmatch me exactly\*(Aq,\*(Aq\-re\*(Aq,\*(Aqmatch\es+me\es+exactly\*(Aq); .Ve .Sp Due to o/s limitations \f(CW$timeout\fR should be a round number. If \f(CW$timeout\fR is 0 Expect will check one time to see if \f(CW$object\fR's handle contains any of the match_patterns. If \f(CW$timeout\fR is undef Expect will wait forever for a pattern to match. If you don't want to explicitly put the timeout on all calls to \f(CW\*(C`expect\*(C'\fR, you can set it via the \f(CW\*(C`timeout\*(C'\fR method . If the first argument of \f(CW\*(C`expect\*(C'\fR doesn't look like a number, that value will be used. .Sp .Vb 2 \& $object\->timeout(15); \& $object\->expect(\*(Aqmatch me exactly\*(Aq,\*(Aq\-re\*(Aq,\*(Aqmatch\es+me\es+exactly\*(Aq); .Ve .Sp If called in a scalar context, \fBexpect()\fR will return the position of the matched pattern within \f(CW@matched_patterns\fR, or undef if no pattern was matched. This is a position starting from 1, so if you want to know which of an array of \f(CW@matched_patterns\fR matched you should subtract one from the return value. .Sp If called in an array context \fBexpect()\fR will return ($matched_pattern_position, \f(CW$error\fR, \f(CW$successfully_matching_string\fR, \&\f(CW$before_match\fR, and \f(CW$after_match\fR). .Sp \&\f(CW$matched_pattern_position\fR will contain the value that would have been returned if \fBexpect()\fR had been called in a scalar context. .Sp \&\f(CW$error\fR is the error that occurred that caused \fBexpect()\fR to return. \f(CW$error\fR will contain a number followed by a string equivalent expressing the nature of the error. Possible values are undef, indicating no error, \&'1:TIMEOUT' indicating that \f(CW$timeout\fR seconds had elapsed without a match, '2:EOF' indicating an eof was read from \f(CW$object\fR, '3: spawn id($fileno) died' indicating that the process exited before matching and '4:$!' indicating whatever error was set in \f(CW$ERRNO\fR during the last read on \f(CW$object\fR's handle or during \fBselect()\fR. All handles indicated by set_group plus \s-1STDOUT\s0 will have all data to come out of \f(CW$object\fR printed to them during \fBexpect()\fR if log_group and log_stdout are set. .Sp \&\f(CW$successfully_matching_string\fR \&\f(CW$before_match\fR \&\f(CW$after_match\fR .Sp Changed from older versions is the regular expression handling. By default now all strings passed to \fBexpect()\fR are treated as literals. To match a regular expression pass '\-re' as a parameter in front of the pattern you want to match as a regexp. .Sp This change makes it possible to match literals and regular expressions in the same \fBexpect()\fR call. .Sp Also new is multiline matching. ^ will now match the beginning of lines. Unfortunately, because perl doesn't use $/ in determining where lines break using $ to find the end of a line frequently doesn't work. This is because your terminal is returning \*(L"\er\en\*(R" at the end of every line. One way to check for a pattern at the end of a line would be to use \er?$ instead of $. .Sp Example: Spawning telnet to a host, you might look for the escape character. telnet would return to you \*(L"\er\enEscape character is \&'^]'.\er\en\*(R". To find this you might use \f(CW$match\fR='^Escape char.*\e.\er?$'; .Sp .Vb 1 \& $telnet\->expect(10,\*(Aq\-re\*(Aq,$match); .Ve .IP "New more Tcl/Expect\-like interface" 4 .IX Item "New more Tcl/Expect-like interface" .Vb 11 \& expect($timeout, \& \*(Aq\-i\*(Aq, [ $obj1, $obj2, ... ], \& [ $re_pattern, sub { ...; exp_continue; }, @subparms, ], \& [ \*(Aqeof\*(Aq, sub { ... } ], \& [ \*(Aqtimeout\*(Aq, sub { ... }, \e$subparm1 ], \& \*(Aq\-i\*(Aq, [ $objn, ...], \& \*(Aq\-ex\*(Aq, $exact_pattern, sub { ... }, \& $exact_pattern, sub { ...; exp_continue_timeout; }, \& \*(Aq\-re\*(Aq, $re_pattern, sub { ... }, \& \*(Aq\-i\*(Aq, \e@object_list, @pattern_list, \& ...); .Ve .Sp It's now possible to expect on more than one connection at a time by specifying '\f(CW\*(C`\-i\*(C'\fR' and a single Expect object or a ref to an array containing Expect objects, e.g. .Sp .Vb 4 \& expect($timeout, \& \*(Aq\-i\*(Aq, $exp1, @patterns_1, \& \*(Aq\-i\*(Aq, [ $exp2, $exp3 ], @patterns_2_3, \& ) .Ve .Sp Furthermore, patterns can now be specified as array refs containing [$regexp, sub { ...}, \f(CW@optional_subprams\fR] . When the pattern matches, the subroutine is called with parameters ($matched_expect_obj, \&\f(CW@optional_subparms\fR). The subroutine can return the symbol `exp_continue' to continue the expect matching with timeout starting anew or return the symbol `exp_continue_timeout' for continuing expect without resetting the timeout count. .Sp .Vb 8 \& $exp\->expect($timeout, \& [ qr/username: /i, sub { my $self = shift; \& $self\->send("$username\en"); \& exp_continue; }], \& [ qr/password: /i, sub { my $self = shift; \& $self\->send("$password\en"); \& exp_continue; }], \& $shell_prompt); .Ve .Sp `expect' is now exported by default. .RE .RS 4 .RE .ie n .IP "$object\->\fBexp_before()\fR \fIor\fR" 4 .el .IP "\f(CW$object\fR\->\fBexp_before()\fR \fIor\fR" 4 .IX Item "$object->exp_before() or" .PD 0 .ie n .IP "$object\->\fBbefore()\fR" 4 .el .IP "\f(CW$object\fR\->\fBbefore()\fR" 4 .IX Item "$object->before()" .PD \&\fBbefore()\fR returns the 'before' part of the last \fBexpect()\fR call. If the last \&\fBexpect()\fR call didn't match anything, \fBexp_before()\fR will return the entire output of the object accumulated before the \fBexpect()\fR call finished. .Sp Note that this is something different than Tcl Expects \fBbefore()\fR!! .ie n .IP "$object\->\fBexp_after()\fR \fIor\fR" 4 .el .IP "\f(CW$object\fR\->\fBexp_after()\fR \fIor\fR" 4 .IX Item "$object->exp_after() or" .PD 0 .ie n .IP "$object\->\fBafter()\fR" 4 .el .IP "\f(CW$object\fR\->\fBafter()\fR" 4 .IX Item "$object->after()" .PD returns the 'after' part of the last \fBexpect()\fR call. If the last \&\fBexpect()\fR call didn't match anything, \fBexp_after()\fR will return \fBundef()\fR. .ie n .IP "$object\->\fBexp_match()\fR \fIor\fR" 4 .el .IP "\f(CW$object\fR\->\fBexp_match()\fR \fIor\fR" 4 .IX Item "$object->exp_match() or" .PD 0 .ie n .IP "$object\->\fBmatch()\fR" 4 .el .IP "\f(CW$object\fR\->\fBmatch()\fR" 4 .IX Item "$object->match()" .PD returns the string matched by the last \fBexpect()\fR call, undef if no string was matched. .ie n .IP "$object\->\fBexp_match_number()\fR \fIor\fR" 4 .el .IP "\f(CW$object\fR\->\fBexp_match_number()\fR \fIor\fR" 4 .IX Item "$object->exp_match_number() or" .PD 0 .ie n .IP "$object\->\fBmatch_number()\fR" 4 .el .IP "\f(CW$object\fR\->\fBmatch_number()\fR" 4 .IX Item "$object->match_number()" .PD \&\fBexp_match_number()\fR returns the number of the pattern matched by the last \&\fBexpect()\fR call. Keep in mind that the first pattern in a list of patterns is 1, not 0. Returns undef if no pattern was matched. .ie n .IP "$object\->\fBexp_matchlist()\fR \fIor\fR" 4 .el .IP "\f(CW$object\fR\->\fBexp_matchlist()\fR \fIor\fR" 4 .IX Item "$object->exp_matchlist() or" .PD 0 .ie n .IP "$object\->\fBmatchlist()\fR" 4 .el .IP "\f(CW$object\fR\->\fBmatchlist()\fR" 4 .IX Item "$object->matchlist()" .PD \&\fBexp_matchlist()\fR returns a list of matched substrings from the brackets () inside the regexp that last matched. ($object\->matchlist)[0] thus corresponds to \f(CW$1\fR, ($object\->matchlist)[1] to \f(CW$2\fR, etc. .ie n .IP "$object\->\fBexp_error()\fR \fIor\fR" 4 .el .IP "\f(CW$object\fR\->\fBexp_error()\fR \fIor\fR" 4 .IX Item "$object->exp_error() or" .PD 0 .ie n .IP "$object\->\fBerror()\fR" 4 .el .IP "\f(CW$object\fR\->\fBerror()\fR" 4 .IX Item "$object->error()" .PD \&\fBexp_error()\fR returns the error generated by the last \fBexpect()\fR call if no pattern was matched. It is typically useful to examine the value returned by \&\fBbefore()\fR to find out what the output of the object was in determining why it didn't match any of the patterns. .ie n .IP "$object\->\fBclear_accum()\fR" 4 .el .IP "\f(CW$object\fR\->\fBclear_accum()\fR" 4 .IX Item "$object->clear_accum()" Clear the contents of the accumulator for \f(CW$object\fR. This gets rid of any residual contents of a handle after \fBexpect()\fR or \fBsend_slow()\fR such that the next \fBexpect()\fR call will only see new data from \f(CW$object\fR. The contents of the accumulator are returned. .ie n .IP "$object\->set_accum($value)" 4 .el .IP "\f(CW$object\fR\->set_accum($value)" 4 .IX Item "$object->set_accum($value)" Sets the content of the accumulator for \f(CW$object\fR to \f(CW$value\fR. The previous content of the accumulator is returned. .ie n .IP "$object\->\fBexp_command()\fR \fIor\fR" 4 .el .IP "\f(CW$object\fR\->\fBexp_command()\fR \fIor\fR" 4 .IX Item "$object->exp_command() or" .PD 0 .ie n .IP "$object\->\fBcommand()\fR" 4 .el .IP "\f(CW$object\fR\->\fBcommand()\fR" 4 .IX Item "$object->command()" .PD \&\fBexp_command()\fR returns the string that was used to spawn the command. Helpful for debugging and for reused patternmatch subroutines. .ie n .IP "$object\->\fBexp_exitstatus()\fR \fIor\fR" 4 .el .IP "\f(CW$object\fR\->\fBexp_exitstatus()\fR \fIor\fR" 4 .IX Item "$object->exp_exitstatus() or" .PD 0 .ie n .IP "$object\->\fBexitstatus()\fR" 4 .el .IP "\f(CW$object\fR\->\fBexitstatus()\fR" 4 .IX Item "$object->exitstatus()" .PD Returns the exit status of \f(CW$object\fR (if it already exited). .ie n .IP "$object\->\fBexp_pty_handle()\fR \fIor\fR" 4 .el .IP "\f(CW$object\fR\->\fBexp_pty_handle()\fR \fIor\fR" 4 .IX Item "$object->exp_pty_handle() or" .PD 0 .ie n .IP "$object\->\fBpty_handle()\fR" 4 .el .IP "\f(CW$object\fR\->\fBpty_handle()\fR" 4 .IX Item "$object->pty_handle()" .PD Returns a string representation of the attached pty, for example: `spawn \fBid\fR\|(5)' (pty has fileno 5), `handle \fBid\fR\|(7)' (pty was initialized from fileno 7) or `\s-1STDIN\s0'. Useful for debugging. .ie n .IP "$object\->restart_timeout_upon_receive(0 | 1)" 4 .el .IP "\f(CW$object\fR\->restart_timeout_upon_receive(0 | 1)" 4 .IX Item "$object->restart_timeout_upon_receive(0 | 1)" If this is set to 1, the expect timeout is retriggered whenever something is received from the spawned command. This allows to perform some aliveness testing and still expect for patterns. .Sp .Vb 5 \& $exp\->restart_timeout_upon_receive(1); \& $exp\->expect($timeout, \& [ timeout => \e&report_timeout ], \& [ qr/pattern/ => \e&handle_pattern], \& ); .Ve .Sp Now the timeout isn't triggered if the command produces any kind of output, i.e. is still alive, but you can act upon patterns in the output. .ie n .IP "$object\->notransfer(1 | 0)" 4 .el .IP "\f(CW$object\fR\->notransfer(1 | 0)" 4 .IX Item "$object->notransfer(1 | 0)" Do not truncate the content of the accumulator after a match. Normally, the accumulator is set to the remains that come after the matched string. Note that this setting is per object and not per pattern, so if you want to have normal acting patterns that truncate the accumulator, you have to add a .Sp .Vb 1 \& $exp\->set_accum($exp\->after); .Ve .Sp to their callback, e.g. .Sp .Vb 12 \& $exp\->notransfer(1); \& $exp\->expect($timeout, \& # accumulator not truncated, pattern1 will match again \& [ "pattern1" => sub { my $self = shift; \& ... \& } ], \& # accumulator truncated, pattern2 will not match again \& [ "pattern2" => sub { my $self = shift; \& ... \& $self\->set_accum($self\->after()); \& } ], \& ); .Ve .Sp This is only a temporary fix until I can rewrite the pattern matching part so it can take that additional \-notransfer argument. .IP "Expect::interconnect(@objects);" 4 .IX Item "Expect::interconnect(@objects);" Read from \f(CW@objects\fR and print to their \f(CW@listen_groups\fR until an escape sequence is matched from one of \f(CW@objects\fR and the associated function returns 0 or undef. The special escape sequence '\s-1EOF\s0' is matched when an object's handle returns an end of file. Note that it is not necessary to include objects that only accept data in \f(CW@objects\fR since the escape sequence is _read_ from an object. Further note that the listen_group for a write-only object is always empty. Why would you want to have objects listening to \s-1STDOUT\s0 (for example)? By default every member of \f(CW@objects\fR _as well as every member of its listen group_ will be set to 'raw \-echo' for the duration of interconnection. Setting \f(CW$object\fR\->\fBmanual_stty()\fR will stop this behavior per object. The original tty settings will be restored as interconnect exits. .Sp For a generic way to interconnect processes, take a look at IPC::Run. .IP "Expect::test_handles(@objects)" 4 .IX Item "Expect::test_handles(@objects)" Given a set of objects determines which objects' handles have data ready to be read. \fBReturns an array\fR who's members are positions in \f(CW@objects\fR that have ready handles. Returns undef if there are no such handles ready. .IP "Expect::version($version_requested or undef);" 4 .IX Item "Expect::version($version_requested or undef);" Returns current version of Expect. As of .99 earlier versions are not supported. Too many things were changed to make versioning possible. .ie n .IP "$object\->interact( ""\e*FILEHANDLE, $escape_sequence"")" 4 .el .IP "\f(CW$object\fR\->interact( \f(CW\e*FILEHANDLE, $escape_sequence\fR)" 4 .IX Item "$object->interact( *FILEHANDLE, $escape_sequence)" \&\fBinteract()\fR is essentially a macro for calling \fBinterconnect()\fR for connecting 2 processes together. \e*FILEHANDLE defaults to \e*STDIN and \&\f(CW$escape_sequence\fR defaults to undef. Interaction ceases when \f(CW$escape_sequence\fR is read from \fB\s-1FILEHANDLE\s0\fR, not \f(CW$object\fR. \f(CW$object\fR's listen group will consist solely of \e*FILEHANDLE for the duration of the interaction. \&\e*FILEHANDLE will not be echoed on \s-1STDOUT.\s0 .ie n .IP "$object\->log_group(0 | 1 | undef)" 4 .el .IP "\f(CW$object\fR\->log_group(0 | 1 | undef)" 4 .IX Item "$object->log_group(0 | 1 | undef)" Set/unset logging of \f(CW$object\fR to its 'listen group'. If set all objects in the listen group will have output from \f(CW$object\fR printed to them during \&\f(CW$object\fR\->\fBexpect()\fR, \f(CW$object\fR\->\fBsend_slow()\fR, and \f(CW\*(C`Expect::interconnect($object , ...)\*(C'\fR. Default value is on. During creation of \f(CW$object\fR the setting will match the value of \f(CW$Expect::Log_Group\fR, normally 1. .ie n .IP "$object\->log_user(0 | 1 | undef) \fIor\fR" 4 .el .IP "\f(CW$object\fR\->log_user(0 | 1 | undef) \fIor\fR" 4 .IX Item "$object->log_user(0 | 1 | undef) or" .PD 0 .ie n .IP "$object\->log_stdout(0 | 1 | undef)" 4 .el .IP "\f(CW$object\fR\->log_stdout(0 | 1 | undef)" 4 .IX Item "$object->log_stdout(0 | 1 | undef)" .PD Set/unset logging of object's handle to \s-1STDOUT.\s0 This corresponds to Tcl's log_user variable. Returns current setting if called without parameters. Default setting is off for initialized handles. When a process object is created (not a filehandle initialized with exp_init) the log_stdout setting will match the value of \f(CW$Expect::Log_Stdout\fR variable, normally 1. If/when you initialize \s-1STDIN\s0 it is usually associated with a tty which will by default echo to \s-1STDOUT\s0 anyway, so be careful or you will have multiple echoes. .ie n .IP "$object\->log_file(""filename"" | $filehandle | \e&coderef | undef)" 4 .el .IP "\f(CW$object\fR\->log_file(``filename'' | \f(CW$filehandle\fR | \e&coderef | undef)" 4 .IX Item "$object->log_file(filename | $filehandle | &coderef | undef)" Log session to a file. All characters send to or received from the spawned process are written to the file. Normally appends to the logfile, but you can pass an additional mode of \*(L"w\*(R" to truncate the file upon \fBopen()\fR: .Sp .Vb 1 \& $object\->log_file("filename", "w"); .Ve .Sp Returns the logfilehandle. .Sp If called with an undef value, stops logging and closes logfile: .Sp .Vb 1 \& $object\->log_file(undef); .Ve .Sp If called without argument, returns the logfilehandle: .Sp .Vb 1 \& $fh = $object\->log_file(); .Ve .Sp Can be set to a code ref, which will be called instead of printing to the logfile: .Sp .Vb 1 \& $object\->log_file(\e&myloggerfunc); .Ve .ie n .IP "$object\->print_log_file(@strings)" 4 .el .IP "\f(CW$object\fR\->print_log_file(@strings)" 4 .IX Item "$object->print_log_file(@strings)" Prints to logfile (if opened) or calls the logfile hook function. This allows the user to add arbitrary text to the logfile. Note that this could also be done as \f(CW$object\fR\->log_file\->\fBprint()\fR but would only work for log files, not code hooks. .ie n .IP "$object\->set_seq($sequence, \e&function, \e@function_parameters)" 4 .el .IP "\f(CW$object\fR\->set_seq($sequence, \e&function, \e@function_parameters)" 4 .IX Item "$object->set_seq($sequence, &function, @function_parameters)" During Expect\->\fBinterconnect()\fR if \f(CW$sequence\fR is read from \f(CW$object\fR &function will be executed with parameters \f(CW@function_parameters\fR. It is \fB_highly recommended_\fR that the escape sequence be a single character since the likelihood is great that the sequence will be broken into to separate reads from the \f(CW$object\fR's handle, making it impossible to strip \f(CW$sequence\fR from getting printed to \f(CW$object\fR's listen group. \e&function should be something like 'main::control_w_function' and \f(CW@function_parameters\fR should be an array defined by the caller, passed by reference to \fBset_seq()\fR. Your function should return a non-zero value if execution of \fBinterconnect()\fR is to resume after the function returns, zero or undefined if \fBinterconnect()\fR should return after your function returns. The special sequence '\s-1EOF\s0' matches the end of file being reached by \f(CW$object\fR. See \fBinterconnect()\fR for details. .ie n .IP "$object\->set_group(@listener_objects)" 4 .el .IP "\f(CW$object\fR\->set_group(@listener_objects)" 4 .IX Item "$object->set_group(@listener_objects)" \&\f(CW@listener_objects\fR is the list of objects that should have their handles printed to by \f(CW$object\fR when Expect::interconnect, \f(CW$object\fR\->\fBexpect()\fR or \&\f(CW$object\fR\->\fBsend_slow()\fR are called. Calling w/out parameters will return the current list of the listener objects. .ie n .IP "$object\->manual_stty(0 | 1 | undef)" 4 .el .IP "\f(CW$object\fR\->manual_stty(0 | 1 | undef)" 4 .IX Item "$object->manual_stty(0 | 1 | undef)" Sets/unsets whether or not Expect should make reasonable guesses as to when and how to set tty parameters for \f(CW$object\fR. Will match \&\f(CW$Expect::Manual_Stty\fR value (normally 0) when \f(CW$object\fR is created. If called without parameters \fBmanual_stty()\fR will return the current manual_stty setting. .ie n .IP "$object\->match_max($maximum_buffer_length | undef) \fIor\fR" 4 .el .IP "\f(CW$object\fR\->match_max($maximum_buffer_length | undef) \fIor\fR" 4 .IX Item "$object->match_max($maximum_buffer_length | undef) or" .PD 0 .ie n .IP "$object\->max_accum($maximum_buffer_length | undef)" 4 .el .IP "\f(CW$object\fR\->max_accum($maximum_buffer_length | undef)" 4 .IX Item "$object->max_accum($maximum_buffer_length | undef)" .PD Set the maximum accumulator size for object. This is useful if you think that the accumulator will grow out of hand during \fBexpect()\fR calls. Since the buffer will be matched by every match_pattern it may get slow if the buffer gets too large. Returns current value if called without parameters. Not defined by default. .ie n .IP "$object\->notransfer(0 | 1)" 4 .el .IP "\f(CW$object\fR\->notransfer(0 | 1)" 4 .IX Item "$object->notransfer(0 | 1)" If set, matched strings will not be deleted from the accumulator. Returns current value if called without parameters. False by default. .ie n .IP "$object\->\fBexp_pid()\fR \fIor\fR" 4 .el .IP "\f(CW$object\fR\->\fBexp_pid()\fR \fIor\fR" 4 .IX Item "$object->exp_pid() or" .PD 0 .ie n .IP "$object\->\fBpid()\fR" 4 .el .IP "\f(CW$object\fR\->\fBpid()\fR" 4 .IX Item "$object->pid()" .PD Return pid of \f(CW$object\fR, if one exists. Initialized filehandles will not have pids (of course). .ie n .IP "$object\->send_slow($delay, @strings);" 4 .el .IP "\f(CW$object\fR\->send_slow($delay, \f(CW@strings\fR);" 4 .IX Item "$object->send_slow($delay, @strings);" print each character from each string of \f(CW@strings\fR one at a time with \f(CW$delay\fR seconds before each character. This is handy for devices such as modems that can be annoying if you send them data too fast. After each character \&\f(CW$object\fR will be checked to determine whether or not it has any new data ready and if so update the accumulator for future \fBexpect()\fR calls and print the output to \s-1STDOUT\s0 and \f(CW@listen_group\fR if log_stdout and log_group are appropriately set. .SS "Configurable Package Variables:" .IX Subsection "Configurable Package Variables:" .ie n .IP "$Expect::Debug" 4 .el .IP "\f(CW$Expect::Debug\fR" 4 .IX Item "$Expect::Debug" Defaults to 0. Newly created objects have a \f(CW$object\fR\->\fBdebug()\fR value of \f(CW$Expect::Debug\fR. See \f(CW$object\fR\->\fBdebug()\fR; .ie n .IP "$Expect::Do_Soft_Close" 4 .el .IP "\f(CW$Expect::Do_Soft_Close\fR" 4 .IX Item "$Expect::Do_Soft_Close" Defaults to 0. When destroying objects, soft_close may take up to half a minute to shut everything down. From now on, only hard_close will be called, which is less polite but still gives the process a chance to terminate properly. Set this to '1' for old behaviour. .ie n .IP "$Expect::Exp_Internal" 4 .el .IP "\f(CW$Expect::Exp_Internal\fR" 4 .IX Item "$Expect::Exp_Internal" Defaults to 0. Newly created objects have a \f(CW$object\fR\->\fBexp_internal()\fR value of \f(CW$Expect::Exp_Internal\fR. See \f(CW$object\fR\->\fBexp_internal()\fR. .ie n .IP "$Expect::IgnoreEintr" 4 .el .IP "\f(CW$Expect::IgnoreEintr\fR" 4 .IX Item "$Expect::IgnoreEintr" Defaults to 0. If set to 1, when waiting for new data, Expect will ignore \s-1EINTR\s0 errors and restart the \fBselect()\fR call instead. .ie n .IP "$Expect::Log_Group" 4 .el .IP "\f(CW$Expect::Log_Group\fR" 4 .IX Item "$Expect::Log_Group" Defaults to 1. Newly created objects have a \f(CW$object\fR\->\fBlog_group()\fR value of \f(CW$Expect::Log_Group\fR. See \f(CW$object\fR\->\fBlog_group()\fR. .ie n .IP "$Expect::Log_Stdout" 4 .el .IP "\f(CW$Expect::Log_Stdout\fR" 4 .IX Item "$Expect::Log_Stdout" Defaults to 1 for spawned commands, 0 for file handles attached with \fBexp_init()\fR. Newly created objects have a \&\f(CW$object\fR\->\fBlog_stdout()\fR value of \f(CW$Expect::Log_Stdout\fR. See \&\f(CW$object\fR\->\fBlog_stdout()\fR. .ie n .IP "$Expect::Manual_Stty" 4 .el .IP "\f(CW$Expect::Manual_Stty\fR" 4 .IX Item "$Expect::Manual_Stty" Defaults to 0. Newly created objects have a \f(CW$object\fR\->\fBmanual_stty()\fR value of \f(CW$Expect::Manual_Stty\fR. See \f(CW$object\fR\->\fBmanual_stty()\fR. .ie n .IP "$Expect::Multiline_Matching" 4 .el .IP "\f(CW$Expect::Multiline_Matching\fR" 4 .IX Item "$Expect::Multiline_Matching" Defaults to 1. Affects whether or not \fBexpect()\fR uses the /m flag for doing regular expression matching. If set to 1 /m is used. .Sp This makes a difference when you are trying to match ^ and $. If you have this on you can match lines in the middle of a page of output using ^ and $ instead of it matching the beginning and end of the entire expression. I think this is handy. .Sp The \f(CW$Expect::Multiline_Matching\fR turns on and off Expect's multi-line matching mode. But this only has an effect if you pass in a string, and then use '\-re' mode. If you pass in a regular expression value (via qr//), then the qr//'s own flags are preserved irrespective of what it gets interpolated into. There was a bug in Perl 5.8.x where interpolating a regex without /m into a match with /m would incorrectly apply the /m to the inner regex too, but this was fixed in Perl 5.10. The correct behavior, as seen in Perl 5.10, is that if you pass in a regex (via qr//), then \f(CW$Expect::Multiline_Matching\fR has no effect. So if you pass in a regex, then you must use the qr's flags to control whether it is multiline (which by default it is not, opposite of the default behavior of Expect). .SH "CONTRIBUTIONS" .IX Header "CONTRIBUTIONS" Lee Eakin has ported the kibitz script from Tcl/Expect to Perl/Expect. .PP Jeff Carr provided a simple example of how handle terminal window resize events (transmitted via the \s-1WINCH\s0 signal) in a ssh session. .PP You can find both scripts in the examples/ subdir. Thanks to both! .PP Historical notes: .PP There are still a few lines of code dating back to the inspirational Comm.pl and Chat.pl modules without which this would not have been possible. Kudos to Eric Arnold and Randal 'Nuke your \s-1NT\s0 box with one line of perl code' Schwartz for making these available to the perl public. .PP As of .98 I think all the old code is toast. No way could this have been done without it though. Special thanks to Graham Barr for helping make sense of the IO::Handle stuff as well as providing the highly recommended IO::Tty module. .SH "REFERENCES" .IX Header "REFERENCES" Mark Rogaski wrote: .PP \&\*(L"I figured that you'd like to know that Expect.pm has been very useful to \s-1AT&T\s0 Labs over the past couple of years (since I first talked to Austin about design decisions). We use Expect.pm for managing the switches in our network via the telnet interface, and such automation has significantly increased our reliability. So, you can honestly say that one of the largest digital networks in existence (\s-1AT&T\s0 Frame Relay) uses Expect.pm quite extensively.\*(R" .SH "FAQ \- Frequently Asked Questions" .IX Header "FAQ - Frequently Asked Questions" This is a growing collection of things that might help. Please send you questions that are not answered here to RGiersig@cpan.org .SS "What systems does Expect run on?" .IX Subsection "What systems does Expect run on?" Expect itself doesn't have real system dependencies, but the underlying IO::Tty needs pseudoterminals. IO::Stty uses \s-1POSIX\s0.pm and Fcntl.pm. .PP I have used it on Solaris, Linux and \s-1AIX,\s0 others report *BSD and \s-1OSF\s0 as working. Generally, any modern \s-1POSIX\s0 Unix should do, but there are exceptions to every rule. Feedback is appreciated. .PP See IO::Tty for a list of verified systems. .SS "Can I use this module with ActivePerl on Windows?" .IX Subsection "Can I use this module with ActivePerl on Windows?" Up to now, the answer was 'No', but this has changed. .PP You still cannot use ActivePerl, but if you use the Cygwin environment (http://sources.redhat.com), which brings its own perl, and have the latest IO::Tty (v0.05 or later) installed, it should work (feedback appreciated). .SS "The examples in the tutorial don't work!" .IX Subsection "The examples in the tutorial don't work!" The tutorial is hopelessly out of date and needs a serious overhaul. I apologize for this, I have concentrated my efforts mainly on the functionality. Volunteers welcomed. .SS "How can I find out what Expect is doing?" .IX Subsection "How can I find out what Expect is doing?" If you set .PP .Vb 1 \& $Expect::Exp_Internal = 1; .Ve .PP Expect will tell you very verbosely what it is receiving and sending, what matching it is trying and what it found. You can do this on a per-command base with .PP .Vb 1 \& $exp\->exp_internal(1); .Ve .PP You can also set .PP .Vb 1 \& $Expect::Debug = 1; # or 2, 3 for more verbose output .Ve .PP or .PP .Vb 1 \& $exp\->debug(1); .Ve .PP which gives you even more output. .SS "I am seeing the output of the command I spawned. Can I turn that off?" .IX Subsection "I am seeing the output of the command I spawned. Can I turn that off?" Yes, just set .PP .Vb 1 \& $Expect::Log_Stdout = 0; .Ve .PP to globally disable it or .PP .Vb 1 \& $exp\->log_stdout(0); .Ve .PP for just that command. 'log_user' is provided as an alias so Tcl/Expect user get a \s-1DWIM\s0 experience... :\-) .SS "No, I mean that when I send some text to the spawned process, it gets echoed back and I have to deal with it in the next expect." .IX Subsection "No, I mean that when I send some text to the spawned process, it gets echoed back and I have to deal with it in the next expect." This is caused by the pty, which has probably 'echo' enabled. A solution would be to set the pty to raw mode, which in general is cleaner for communication between two programs (no more unexpected character translations). Unfortunately this would break a lot of old code that sends \*(L"\er\*(R" to the program instead of \*(L"\en\*(R" (translating this is also handled by the pty), so I won't add this to Expect just like that. But feel free to experiment with \f(CW\*(C`$exp\->raw_pty(1)\*(C'\fR. .SS "How do I send control characters to a process?" .IX Subsection "How do I send control characters to a process?" A: You can send any characters to a process with the print command. To represent a control character in Perl, use \ec followed by the letter. For example, control-G can be represented with \*(L"\ecG\*(R" . Note that this will not work if you single-quote your string. So, to send control-C to a process in \&\f(CW$exp\fR, do: .PP .Vb 1 \& print $exp "\ecC"; .Ve .PP Or, if you prefer: .PP .Vb 1 \& $exp\->send("\ecC"); .Ve .PP The ability to include control characters in a string like this is provided by Perl, not by Expect.pm . Trying to learn Expect.pm without a thorough grounding in Perl can be very daunting. We suggest you look into some of the excellent Perl learning material, such as the books _Programming Perl_ and _Learning Perl_ by O'Reilly, as well as the extensive online Perl documentation available through the perldoc command. .SS "My script fails from time to time without any obvious reason. It seems that I am sometimes loosing output from the spawned program." .IX Subsection "My script fails from time to time without any obvious reason. It seems that I am sometimes loosing output from the spawned program." You could be exiting too fast without giving the spawned program enough time to finish. Try adding \f(CW$exp\fR\->\fBsoft_close()\fR to terminate the program gracefully or do an \fBexpect()\fR for 'eof'. .PP Alternatively, try adding a 'sleep 1' after you \fBspawn()\fR the program. It could be that pty creation on your system is just slow (but this is rather improbable if you are using the latest IO-Tty). .SS "I want to automate password entry for su/ssh/scp/rsh/..." .IX Subsection "I want to automate password entry for su/ssh/scp/rsh/..." You shouldn't use Expect for this. Putting passwords, especially root passwords, into scripts in clear text can mean severe security problems. I strongly recommend using other means. For 'su', consider switching to 'sudo', which gives you root access on a per-command and per-user basis without the need to enter passwords. 'ssh'/'scp' can be set up with \s-1RSA\s0 authentication without passwords. 'rsh' can use the .rhost mechanism, but I'd strongly suggest to switch to 'ssh'; to mention 'rsh' and 'security' in the same sentence makes an oxymoron. .PP It will work for 'telnet', though, and there are valid uses for it, but you still might want to consider using 'ssh', as keeping cleartext passwords around is very insecure. .SS "I want to use Expect to automate [anything with a buzzword]..." .IX Subsection "I want to use Expect to automate [anything with a buzzword]..." Are you sure there is no other, easier way? As a rule of thumb, Expect is useful for automating things that expect to talk to a human, where no formal standard applies. For other tasks that do follow a well-defined protocol, there are often better-suited modules that already can handle those protocols. Don't try to do \s-1HTTP\s0 requests by spawning telnet to port 80, use \s-1LWP\s0 instead. To automate \s-1FTP,\s0 take a look at Net::FTP or \f(CW\*(C`ncftp\*(C'\fR (http://www.ncftp.org). You don't use a screwdriver to hammer in your nails either, or do you? .SS "Is it possible to use threads with Expect?" .IX Subsection "Is it possible to use threads with Expect?" Basically yes, with one restriction: you must \fBspawn()\fR your programs in the main thread and then pass the Expect objects to the handling threads. The reason is that \fBspawn()\fR uses \fBfork()\fR, and perlthrtut: .PP .Vb 1 \& "Thinking of mixing fork() and threads? Please lie down and wait until the feeling passes." .Ve .SS "I want to log the whole session to a file." .IX Subsection "I want to log the whole session to a file." Use .PP .Vb 1 \& $exp\->log_file("filename"); .Ve .PP or .PP .Vb 1 \& $exp\->log_file($filehandle); .Ve .PP or even .PP .Vb 1 \& $exp\->log_file(\e&log_procedure); .Ve .PP for maximum flexibility. .PP Note that the logfile is appended to by default, but you can specify an optional mode \*(L"w\*(R" to truncate the logfile: .PP .Vb 1 \& $exp\->log_file("filename", "w"); .Ve .PP To stop logging, just call it with a false argument: .PP .Vb 1 \& $exp\->log_file(undef); .Ve .SS "How can I turn off multi-line matching for my regexps?" .IX Subsection "How can I turn off multi-line matching for my regexps?" To globally unset multi-line matching for all regexps: .PP .Vb 1 \& $Expect::Multiline_Matching = 0; .Ve .PP You can do that on a per-regexp basis by stating \f(CW\*(C`(?\-m)\*(C'\fR inside the regexp (you need perl5.00503 or later for that). .SS "How can I expect on multiple spawned commands?" .IX Subsection "How can I expect on multiple spawned commands?" You can use the \fB\-i\fR parameter to specify a single object or a list of Expect objects. All following patterns will be evaluated against that list. .PP You can specify \fB\-i\fR multiple times to create groups of objects and patterns to match against within the same expect statement. .PP This works just like in Tcl/Expect. .PP See the source example below. .SS "I seem to have problems with ptys!" .IX Subsection "I seem to have problems with ptys!" Well, pty handling is really a black magic, as it is extremely system dependent. I have extensively revised IO-Tty, so these problems should be gone. .PP If your system is listed in the \*(L"verified\*(R" list of IO::Tty, you probably have some non-standard setup, e.g. you compiled your Linux-kernel yourself and disabled ptys. Please ask your friendly sysadmin for help. .PP If your system is not listed, unpack the latest version of IO::Tty, do a 'perl Makefile.PL; make; make test; uname \f(CW\*(C`\-a\*(C'\fR' and send me the results and I'll see what I can deduce from that. .SS "I just want to read the output of a process without \fBexpect()\fPing anything. How can I do this?" .IX Subsection "I just want to read the output of a process without expect()ing anything. How can I do this?" [ Are you sure you need Expect for this? How about \fBqx()\fR or open(\*(L"prog|\*(R")? ] .PP By using expect without any patterns to match. .PP .Vb 3 \& $process\->expect(undef); # Forever until EOF \& $process\->expect($timeout); # For a few seconds \& $process\->expect(0); # Is there anything ready on the handle now? .Ve .SS "Ok, so now how do I get what was read on the handle?" .IX Subsection "Ok, so now how do I get what was read on the handle?" .Vb 1 \& $read = $process\->before(); .Ve .SS "Where's IO::Pty?" .IX Subsection "Where's IO::Pty?" Find it on \s-1CPAN\s0 as IO-Tty, which provides both. .SS "How come when I automate the passwd program to change passwords for me passwd dies before changing the password sometimes/every time?" .IX Subsection "How come when I automate the passwd program to change passwords for me passwd dies before changing the password sometimes/every time?" What's happening is you are closing the handle before passwd exits. When you close the handle to a process, it is sent a signal (\s-1SIGPIPE\s0?) telling it that \s-1STDOUT\s0 has gone away. The default behavior for processes is to die in this circumstance. Two ways you can make this not happen are: .PP .Vb 1 \& $process\->soft_close(); .Ve .PP This will wait 15 seconds for a process to come up with an \s-1EOF\s0 by itself before killing it. .PP .Vb 1 \& $process\->expect(undef); .Ve .PP This will wait forever for the process to match an empty set of patterns. It will return when the process hits an \s-1EOF.\s0 .PP As a rule, you should always \fBexpect()\fR the result of your transaction before you continue with processing. .SS "How come when I try to make a logfile with \fBlog_file()\fP or \fBset_group()\fP it doesn't print anything after the last time I run \fBexpect()\fP?" .IX Subsection "How come when I try to make a logfile with log_file() or set_group() it doesn't print anything after the last time I run expect()?" Output is only printed to the logfile/group when Expect reads from the process, during \fBexpect()\fR, \fBsend_slow()\fR and \fBinterconnect()\fR. One way you can force this is to make use of .PP .Vb 1 \& $process\->expect(undef); .Ve .PP and .PP .Vb 1 \& $process\->expect(0); .Ve .PP which will make \fBexpect()\fR run with an empty pattern set forever or just for an instant to capture the output of \f(CW$process\fR. The output is available in the accumulator, so you can grab it using \&\f(CW$process\fR\->\fBbefore()\fR. .SS "I seem to have problems with terminal settings, double echoing, etc." .IX Subsection "I seem to have problems with terminal settings, double echoing, etc." Tty settings are a major pain to keep track of. If you find unexpected behavior such as double-echoing or a frozen session, doublecheck the documentation for default settings. When in doubt, handle them yourself using \f(CW$exp\fR\->\fBstty()\fR and \fBmanual_stty()\fR functions. As of .98 you shouldn't have to worry about stty settings getting fouled unless you use interconnect or intentionally change them (like doing \-echo to get a password). .PP If you foul up your terminal's tty settings, kill any hung processes and enter 'stty sane' at a shell prompt. This should make your terminal manageable again. .PP Note that IO::Tty returns ptys with your systems default setting regarding echoing, \s-1CRLF\s0 translation etc. and Expect does not change them. I have considered setting the ptys to 'raw' without any translation whatsoever, but this would break a lot of existing things, as '\er' translation would not work anymore. On the other hand, a raw pty works much like a pipe and is more \s-1WYGIWYE\s0 (what you get is what you expect), so I suggest you set it to 'raw' by yourself: .PP .Vb 3 \& $exp = Expect\->new; \& $exp\->raw_pty(1); \& $exp\->spawn(...); .Ve .PP To disable echo: .PP .Vb 1 \& $exp\->slave\->stty(qw(\-echo)); .Ve .SS "I'm spawning a telnet/ssh session and then let the user interact with it. But screen-oriented applications on the other side don't work properly." .IX Subsection "I'm spawning a telnet/ssh session and then let the user interact with it. But screen-oriented applications on the other side don't work properly." You have to set the terminal screen size for that. Luckily, IO::Pty already has a method for that, so modify your code to look like this: .PP .Vb 3 \& my $exp = Expect\->new; \& $exp\->slave\->clone_winsize_from(\e*STDIN); \& $exp\->spawn("telnet somehost); .Ve .PP Also, some applications need the \s-1TERM\s0 shell variable set so they know how to move the cursor across the screen. When logging in, the remote shell sends a query (Ctrl-Z I think) and expects the terminal to answer with a string, e.g. 'xterm'. If you really want to go that way (be aware, madness lies at its end), you can handle that and send back the value in \f(CW$ENV\fR{\s-1TERM\s0}. This is only a hand-waving explanation, please figure out the details by yourself. .SS "I set the terminal size as explained above, but if I resize the window, the application does not notice this." .IX Subsection "I set the terminal size as explained above, but if I resize the window, the application does not notice this." You have to catch the signal \s-1WINCH\s0 (\*(L"window size changed\*(R"), change the terminal size and propagate the signal to the spawned application: .PP .Vb 4 \& my $exp = Expect\->new; \& $exp\->slave\->clone_winsize_from(\e*STDIN); \& $exp\->spawn("ssh somehost); \& $SIG{WINCH} = \e&winch; \& \& sub winch { \& $exp\->slave\->clone_winsize_from(\e*STDIN); \& kill WINCH => $exp\->pid if $exp\->pid; \& $SIG{WINCH} = \e&winch; \& } \& \& $exp\->interact(); .Ve .PP There is an example file ssh.pl in the examples/ subdir that shows how this works with ssh. Please note that I do strongly object against using Expect to automate ssh login, as there are better way to do that (see ssh-keygen). .SS "I noticed that the test uses a string that resembles, but not exactly matches, a well-known sentence that contains every character. What does that mean?" .IX Subsection "I noticed that the test uses a string that resembles, but not exactly matches, a well-known sentence that contains every character. What does that mean?" That means you are anal-retentive. :\-) [Gotcha there!] .ie n .SS "I get a ""Could not assign a pty"" error when running as a non-root user on an \s-1IRIX\s0 box?" .el .SS "I get a ``Could not assign a pty'' error when running as a non-root user on an \s-1IRIX\s0 box?" .IX Subsection "I get a Could not assign a pty error when running as a non-root user on an IRIX box?" The \s-1OS\s0 may not be configured to grant additional pty's (pseudo terminals) to non-root users. /usr/sbin/mkpts should be 4755, not 700 for this to work. I don't know about security implications if you do this. .SS "How come I don't notice when the spawned process closes its stdin/out/err??" .IX Subsection "How come I don't notice when the spawned process closes its stdin/out/err??" You are probably on one of the systems where the master doesn't get an \&\s-1EOF\s0 when the slave closes stdin/out/err. .PP One possible solution is when you spawn a process, follow it with a unique string that would indicate the process is finished. .PP .Vb 1 \& $process = Expect\->spawn(\*(Aqtelnet somehost; echo _\|_\|_\|_END_\|_\|_\|_\*(Aq); .Ve .PP And then \f(CW$process\fR\->expect($timeout,'_\|_\|_\|_END_\|_\|_\|_','other','patterns'); .SH "Source Examples" .IX Header "Source Examples" .SS "How to automate login" .IX Subsection "How to automate login" .Vb 3 \& my $telnet = Net::Telnet\->new("remotehost") # see Net::Telnet \& or die "Cannot telnet to remotehost: $!\en";; \& my $exp = Expect\->exp_init($telnet); \& \& # deprecated use of spawned telnet command \& # my $exp = Expect\->spawn("telnet localhost") \& # or die "Cannot spawn telnet: $!\en";; \& \& my $spawn_ok; \& $exp\->expect($timeout, \& [ \& qr\*(Aqlogin: $\*(Aq, \& sub { \& $spawn_ok = 1; \& my $fh = shift; \& $fh\->send("$username\en"); \& exp_continue; \& } \& ], \& [ \& \*(AqPassword: $\*(Aq, \& sub { \& my $fh = shift; \& print $fh "$password\en"; \& exp_continue; \& } \& ], \& [ \& eof => \& sub { \& if ($spawn_ok) { \& die "ERROR: premature EOF in login.\en"; \& } else { \& die "ERROR: could not spawn telnet.\en"; \& } \& } \& ], \& [ \& timeout => \& sub { \& die "No login.\en"; \& } \& ], \& \*(Aq\-re\*(Aq, qr\*(Aq[#>:] $\*(Aq, #\*(Aq wait for shell prompt, then exit expect \& ); .Ve .SS "How to expect on multiple spawned commands" .IX Subsection "How to expect on multiple spawned commands" .Vb 3 \& foreach my $cmd (@list_of_commands) { \& push @commands, Expect\->spawn($cmd); \& } \& \& expect($timeout, \& \*(Aq\-i\*(Aq, \e@commands, \& [ \& qr"pattern", # find this pattern in output of all commands \& sub { \& my $obj = shift; # object that matched \& print $obj "something\en"; \& exp_continue; # we don\*(Aqt want to terminate the expect call \& } \& ], \& \*(Aq\-i\*(Aq, $some_other_command, \& [ \& "some other pattern", \& sub { \& my ($obj, $parmref) = @_; \& # ... \& \& # now we exit the expect command \& }, \& \e$parm \& ], \& ); .Ve .SS "How to propagate terminal sizes" .IX Subsection "How to propagate terminal sizes" .Vb 4 \& my $exp = Expect\->new; \& $exp\->slave\->clone_winsize_from(\e*STDIN); \& $exp\->spawn("ssh somehost); \& $SIG{WINCH} = \e&winch; \& \& sub winch { \& $exp\->slave\->clone_winsize_from(\e*STDIN); \& kill WINCH => $exp\->pid if $exp\->pid; \& $SIG{WINCH} = \e&winch; \& } \& \& $exp\->interact(); .Ve .SH "HOMEPAGE" .IX Header "HOMEPAGE" though the source code is now in GitHub: .SH "MAILING LISTS" .IX Header "MAILING LISTS" There are two mailing lists available, expectperl-announce and expectperl-discuss, at .PP .Vb 1 \& http://lists.sourceforge.net/lists/listinfo/expectperl\-announce .Ve .PP and .PP .Vb 1 \& http://lists.sourceforge.net/lists/listinfo/expectperl\-discuss .Ve .SH "BUG TRACKING" .IX Header "BUG TRACKING" You can use the \s-1CPAN\s0 Request Tracker http://rt.cpan.org/ and submit new bugs under .PP .Vb 1 \& http://rt.cpan.org/Ticket/Create.html?Queue=Expect .Ve .SH "AUTHORS" .IX Header "AUTHORS" (c) 1997 Austin Schutz <\fIASchutz@users.sourceforge.net\fR> (retired) .PP \&\fBexpect()\fR interface & functionality enhancements (c) 1999\-2006 Roland Giersig. .PP This module is now maintained by Dave Jacoby <\fIjacoby@cpan.org\fR> .SH "LICENSE" .IX Header "LICENSE" This module can be used under the same terms as Perl. .SH "DISCLAIMER" .IX Header "DISCLAIMER" \&\s-1THIS SOFTWARE IS PROVIDED\s0 ``\s-1AS IS\s0'' \s-1AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\s0 .PP In other words: Use at your own risk. Provided as is. Your mileage may vary. Read the source, Luke! .PP And finally, just to be sure: .PP Any Use of This Product, in Any Manner Whatsoever, Will Increase the Amount of Disorder in the Universe. Although No Liability Is Implied Herein, the Consumer Is Warned That This Process Will Ultimately Lead to the Heat Death of the Universe. PK@O\z!! IO::Pty.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Pty 3" .TH Pty 3 "2023-12-28" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" IO::Pty \- Pseudo TTY object class .SH "VERSION" .IX Header "VERSION" 1.20 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use IO::Pty; \& \& $pty = new IO::Pty; \& \& $slave = $pty\->slave; \& \& foreach $val (1..10) { \& print $pty "$val\en"; \& $_ = <$slave>; \& print "$_"; \& } \& \& close($slave); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`IO::Pty\*(C'\fR provides an interface to allow the creation of a pseudo tty. .PP \&\f(CW\*(C`IO::Pty\*(C'\fR inherits from \f(CW\*(C`IO::Handle\*(C'\fR and so provide all the methods defined by the \f(CW\*(C`IO::Handle\*(C'\fR package. .PP Please note that pty creation is very system-dependent. If you have problems, see IO::Tty for help. .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .IP "new" 3 .IX Item "new" The \f(CW\*(C`new\*(C'\fR constructor takes no arguments and returns a new file object which is the master side of the pseudo tty. .SH "METHODS" .IX Header "METHODS" .IP "\fBttyname()\fR" 4 .IX Item "ttyname()" Returns the name of the slave pseudo tty. On \s-1UNIX\s0 machines this will be the pathname of the device. Use this name for informational purpose only, to get a slave filehandle, use \fBslave()\fR. .IP "\fBslave()\fR" 4 .IX Item "slave()" The \f(CW\*(C`slave\*(C'\fR method will return the slave filehandle of the given master pty, opening it anew if necessary. If IO::Stty is installed, you can then call \f(CW\*(C`$slave\->stty()\*(C'\fR to modify the terminal settings. .IP "\fBclose_slave()\fR" 4 .IX Item "close_slave()" The slave filehandle will be closed and destroyed. This is necessary in the parent after forking to get rid of the open filehandle, otherwise the parent will not notice if the child exits. Subsequent calls of \f(CW\*(C`slave()\*(C'\fR will return a newly opened slave filehandle. .IP "\fBmake_slave_controlling_terminal()\fR" 4 .IX Item "make_slave_controlling_terminal()" This will set the slave filehandle as the controlling terminal of the current process, which will become a session leader, so this should only be called by a child process after a \fBfork()\fR, e.g. in the callback to \f(CW\*(C`sync_exec()\*(C'\fR (see Proc::SyncExec). See the \f(CW\*(C`try\*(C'\fR script (also \f(CW\*(C`test.pl\*(C'\fR) for an example how to correctly spawn a subprocess. .IP "\fBset_raw()\fR" 4 .IX Item "set_raw()" Will set the pty to raw. Note that this is a one-way operation, you need IO::Stty to set the terminal settings to anything else. .Sp On some systems, the master pty is not a tty. This method checks for that and returns success anyway on such systems. Note that this method must be called on the slave, and probably should be called on the master, just to be sure, i.e. .Sp .Vb 2 \& $pty\->slave\->set_raw(); \& $pty\->set_raw(); .Ve .IP "clone_winsize_from(\e*FH)" 4 .IX Item "clone_winsize_from(*FH)" Gets the terminal size from filehandle \s-1FH\s0 (which must be a terminal) and transfers it to the pty. Returns true on success and undef on failure. Note that this must be called upon the \fIslave\fR, i.e. .Sp .Vb 1 \& $pty\->slave\->clone_winsize_from(\e*STDIN); .Ve .Sp On some systems, the master pty also isatty. I actually have no idea if setting terminal sizes there is passed through to the slave, so if this method is called for a master that is not a tty, it silently returns \s-1OK.\s0 .Sp See the \f(CW\*(C`try\*(C'\fR script for example code how to propagate \s-1SIGWINCH.\s0 .IP "\fBget_winsize()\fR" 4 .IX Item "get_winsize()" Returns the terminal size, in a 4\-element list. .Sp .Vb 1 \& ($row, $col, $xpixel, $ypixel) = $tty\->get_winsize() .Ve .ie n .IP "set_winsize($row, $col, $xpixel, $ypixel)" 4 .el .IP "set_winsize($row, \f(CW$col\fR, \f(CW$xpixel\fR, \f(CW$ypixel\fR)" 4 .IX Item "set_winsize($row, $col, $xpixel, $ypixel)" Sets the terminal size. If not specified, \f(CW$xpixel\fR and \f(CW$ypixel\fR are set to 0. As with \f(CW\*(C`clone_winsize_from\*(C'\fR, this must be called upon the \fIslave\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" IO::Tty, IO::Tty::Constant, IO::Handle, Expect, Proc::SyncExec .SH "MAILING LISTS" .IX Header "MAILING LISTS" As this module is mainly used by Expect, support for it is available via the two Expect mailing lists, expectperl-announce and expectperl-discuss, at .PP .Vb 1 \& http://lists.sourceforge.net/lists/listinfo/expectperl\-announce .Ve .PP and .PP .Vb 1 \& http://lists.sourceforge.net/lists/listinfo/expectperl\-discuss .Ve .SH "AUTHORS" .IX Header "AUTHORS" Originally by Graham Barr <\fIgbarr@pobox.com\fR>, based on the Ptty module by Nick Ing-Simmons <\fInik@tiuk.ti.com\fR>. .PP Now maintained and heavily rewritten by Roland Giersig <\fIRGiersig@cpan.org\fR>. .PP Contains copyrighted stuff from openssh v3.0p1, authored by Tatu Ylonen , Markus Friedl and Todd C. Miller . .SH "COPYRIGHT" .IX Header "COPYRIGHT" Now all code is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP Nevertheless the above \s-1AUTHORS\s0 retain their copyrights to the various parts and want to receive credit if their source code is used. See the source for details. .SH "DISCLAIMER" .IX Header "DISCLAIMER" \&\s-1THIS SOFTWARE IS PROVIDED\s0 ``\s-1AS IS\s0'' \s-1AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES\s0 (\s-1INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\s0 .PP In other words: Use at your own risk. Provided as is. Your mileage may vary. Read the source, Luke! .PP And finally, just to be sure: .PP Any Use of This Product, in Any Manner Whatsoever, Will Increase the Amount of Disorder in the Universe. Although No Liability Is Implied Herein, the Consumer Is Warned That This Process Will Ultimately Lead to the Heat Death of the Universe. PK@O\EX:22 App::Cpan.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "App::Cpan 3" .TH App::Cpan 3 "2022-04-03" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" App::Cpan \- easily interact with CPAN from the command line .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # with arguments and no switches, installs specified modules \& cpan module_name [ module_name ... ] \& \& # with switches, installs modules with extra behavior \& cpan [\-cfFimtTw] module_name [ module_name ... ] \& \& # use local::lib \& cpan \-I module_name [ module_name ... ] \& \& # one time mirror override for faster mirrors \& cpan \-p ... \& \& # with just the dot, install from the distribution in the \& # current directory \& cpan . \& \& # without arguments, starts CPAN.pm shell \& cpan \& \& # without arguments, but some switches \& cpan [\-ahpruvACDLOPX] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This script provides a command interface (not a shell) to \s-1CPAN.\s0 At the moment it uses \s-1CPAN\s0.pm to do the work, but it is not a one-shot command runner for \s-1CPAN\s0.pm. .SS "Options" .IX Subsection "Options" .IP "\-a" 4 .IX Item "-a" Creates a \s-1CPAN\s0.pm autobundle with CPAN::Shell\->autobundle. .IP "\-A module [ module ... ]" 4 .IX Item "-A module [ module ... ]" Shows the primary maintainers for the specified modules. .IP "\-c module" 4 .IX Item "-c module" Runs a `make clean` in the specified module's directories. .IP "\-C module [ module ... ]" 4 .IX Item "-C module [ module ... ]" Show the \fIChanges\fR files for the specified modules .IP "\-D module [ module ... ]" 4 .IX Item "-D module [ module ... ]" Show the module details. This prints one line for each out-of-date module (meaning, modules locally installed but have newer versions on \s-1CPAN\s0). Each line has three columns: module name, local version, and \s-1CPAN\s0 version. .IP "\-f" 4 .IX Item "-f" Force the specified action, when it normally would have failed. Use this to install a module even if its tests fail. When you use this option, \&\-i is not optional for installing a module when you need to force it: .Sp .Vb 1 \& % cpan \-f \-i Module::Foo .Ve .IP "\-F" 4 .IX Item "-F" Turn off \s-1CPAN\s0.pm's attempts to lock anything. You should be careful with this since you might end up with multiple scripts trying to muck in the same directory. This isn't so much of a concern if you're loading a special config with \f(CW\*(C`\-j\*(C'\fR, and that config sets up its own work directories. .IP "\-g module [ module ... ]" 4 .IX Item "-g module [ module ... ]" Downloads to the current directory the latest distribution of the module. .IP "\-G module [ module ... ]" 4 .IX Item "-G module [ module ... ]" \&\s-1UNIMPLEMENTED\s0 .Sp Download to the current directory the latest distribution of the modules, unpack each distribution, and create a git repository for each distribution. .Sp If you want this feature, check out Yanick Champoux's \f(CW\*(C`Git::CPAN::Patch\*(C'\fR distribution. .IP "\-h" 4 .IX Item "-h" Print a help message and exit. When you specify \f(CW\*(C`\-h\*(C'\fR, it ignores all of the other options and arguments. .IP "\-i module [ module ... ]" 4 .IX Item "-i module [ module ... ]" Install the specified modules. With no other switches, this switch is implied. .IP "\-I" 4 .IX Item "-I" Load \f(CW\*(C`local::lib\*(C'\fR (think like \f(CW\*(C`\-I\*(C'\fR for loading lib paths). Too bad \&\f(CW\*(C`\-l\*(C'\fR was already taken. .IP "\-j Config.pm" 4 .IX Item "-j Config.pm" Load the file that has the \s-1CPAN\s0 configuration data. This should have the same format as the standard \fICPAN/Config.pm\fR file, which defines \&\f(CW$CPAN::Config\fR as an anonymous hash. .Sp If the file does not exist, \f(CW\*(C`cpan\*(C'\fR dies. .IP "\-J" 4 .IX Item "-J" Dump the configuration in the same format that \s-1CPAN\s0.pm uses. This is useful for checking the configuration as well as using the dump as a starting point for a new, custom configuration. .IP "\-l" 4 .IX Item "-l" List all installed modules with their versions .IP "\-L author [ author ... ]" 4 .IX Item "-L author [ author ... ]" List the modules by the specified authors. .IP "\-m" 4 .IX Item "-m" Make the specified modules. .IP "\-M mirror1,mirror2,..." 4 .IX Item "-M mirror1,mirror2,..." A comma-separated list of mirrors to use for just this run. The \f(CW\*(C`\-P\*(C'\fR option can find them for you automatically. .IP "\-n" 4 .IX Item "-n" Do a dry run, but don't actually install anything. (unimplemented) .IP "\-O" 4 .IX Item "-O" Show the out-of-date modules. .IP "\-p" 4 .IX Item "-p" Ping the configured mirrors and print a report .IP "\-P" 4 .IX Item "-P" Find the best mirrors you could be using and use them for the current session. .IP "\-r" 4 .IX Item "-r" Recompiles dynamically loaded modules with CPAN::Shell\->recompile. .IP "\-s" 4 .IX Item "-s" Drop in the \s-1CPAN\s0.pm shell. This command does this automatically if you don't specify any arguments. .IP "\-t module [ module ... ]" 4 .IX Item "-t module [ module ... ]" Run a `make test` on the specified modules. .IP "\-T" 4 .IX Item "-T" Do not test modules. Simply install them. .IP "\-u" 4 .IX Item "-u" Upgrade all installed modules. Blindly doing this can really break things, so keep a backup. .IP "\-v" 4 .IX Item "-v" Print the script version and \s-1CPAN\s0.pm version then exit. .IP "\-V" 4 .IX Item "-V" Print detailed information about the cpan client. .IP "\-w" 4 .IX Item "-w" \&\s-1UNIMPLEMENTED\s0 .Sp Turn on cpan warnings. This checks various things, like directory permissions, and tells you about problems you might have. .IP "\-x module [ module ... ]" 4 .IX Item "-x module [ module ... ]" Find close matches to the named modules that you think you might have mistyped. This requires the optional installation of Text::Levenshtein or Text::Levenshtein::Damerau. .IP "\-X" 4 .IX Item "-X" Dump all the namespaces to standard output. .SS "Examples" .IX Subsection "Examples" .Vb 2 \& # print a help message \& cpan \-h \& \& # print the version numbers \& cpan \-v \& \& # create an autobundle \& cpan \-a \& \& # recompile modules \& cpan \-r \& \& # upgrade all installed modules \& cpan \-u \& \& # install modules ( sole \-i is optional ) \& cpan \-i Netscape::Booksmarks Business::ISBN \& \& # force install modules ( must use \-i ) \& cpan \-fi CGI::Minimal URI \& \& # install modules but without testing them \& cpan \-Ti CGI::Minimal URI .Ve .SS "Environment variables" .IX Subsection "Environment variables" There are several components in \s-1CPAN\s0.pm that use environment variables. The build tools, ExtUtils::MakeMaker and Module::Build use some, while others matter to the levels above them. Some of these are specified by the Perl Toolchain Gang: .PP Lancaster Consensus: .PP Oslo Consensus: .IP "\s-1NONINTERACTIVE_TESTING\s0" 4 .IX Item "NONINTERACTIVE_TESTING" Assume no one is paying attention and skips prompts for distributions that do that correctly. \f(CWcpan(1)\fR sets this to \f(CW1\fR unless it already has a value (even if that value is false). .IP "\s-1PERL_MM_USE_DEFAULT\s0" 4 .IX Item "PERL_MM_USE_DEFAULT" Use the default answer for a prompted questions. \f(CWcpan(1)\fR sets this to \f(CW1\fR unless it already has a value (even if that value is false). .IP "\s-1CPAN_OPTS\s0" 4 .IX Item "CPAN_OPTS" As with \f(CW\*(C`PERL5OPT\*(C'\fR, a string of additional \f(CWcpan(1)\fR options to add to those you specify on the command line. .IP "\s-1CPANSCRIPT_LOGLEVEL\s0" 4 .IX Item "CPANSCRIPT_LOGLEVEL" The log level to use, with either the embedded, minimal logger or Log::Log4perl if it is installed. Possible values are the same as the \f(CW\*(C`Log::Log4perl\*(C'\fR levels: \f(CW\*(C`TRACE\*(C'\fR, \f(CW\*(C`DEBUG\*(C'\fR, \f(CW\*(C`INFO\*(C'\fR, \f(CW\*(C`WARN\*(C'\fR, \&\f(CW\*(C`ERROR\*(C'\fR, and \f(CW\*(C`FATAL\*(C'\fR. The default is \f(CW\*(C`INFO\*(C'\fR. .IP "\s-1GIT_COMMAND\s0" 4 .IX Item "GIT_COMMAND" The path to the \f(CW\*(C`git\*(C'\fR binary to use for the Git features. The default is \f(CW\*(C`/usr/local/bin/git\*(C'\fR. .SS "Methods" .IX Subsection "Methods" .IP "run( \s-1ARGS\s0 )" 4 .IX Item "run( ARGS )" Just do it. .Sp The \f(CW\*(C`run\*(C'\fR method returns 0 on success and a positive number on failure. See the section on \s-1EXIT CODES\s0 for details on the values. .Sp \&\s-1CPAN\s0.pm sends all the good stuff either to \s-1STDOUT,\s0 or to a temp file if \f(CW$CPAN::Be_Silent\fR is set. I have to intercept that output so I can find out what happened. .Sp Stolen from File::Path::Expand .SH "EXIT VALUES" .IX Header "EXIT VALUES" The script exits with zero if it thinks that everything worked, or a positive number if it thinks that something failed. Note, however, that in some cases it has to divine a failure by the output of things it does not control. For now, the exit codes are vague: .PP .Vb 1 \& 1 An unknown error \& \& 2 The was an external problem \& \& 4 There was an internal problem with the script \& \& 8 A module failed to install .Ve .SH "TO DO" .IX Header "TO DO" * There is initial support for Log4perl if it is available, but I haven't gone through everything to make the NullLogger work out correctly if Log4perl is not installed. .PP * When I capture \s-1CPAN\s0.pm output, I need to check for errors and report them to the user. .PP * Warnings switch .PP * Check then exit .SH "BUGS" .IX Header "BUGS" * none noted .SH "SEE ALSO" .IX Header "SEE ALSO" \&\s-1CPAN\s0, App::cpanminus .SH "SOURCE AVAILABILITY" .IX Header "SOURCE AVAILABILITY" This code is in Github in the \s-1CPAN\s0.pm repository: .PP .Vb 1 \& https://github.com/andk/cpanpm .Ve .PP The source used to be tracked separately in another GitHub repo, but the canonical source is now in the above repo. .SH "CREDITS" .IX Header "CREDITS" Japheth Cleaver added the bits to allow a forced install (\f(CW\*(C`\-f\*(C'\fR). .PP Jim Brandt suggested and provided the initial implementation for the up-to-date and Changes features. .PP Adam Kennedy pointed out that \f(CW\*(C`exit()\*(C'\fR causes problems on Windows where this script ends up with a .bat extension .PP David Golden helps integrate this into the \f(CW\*(C`CPAN.pm\*(C'\fR repos. .PP Jim Keenan fixed up various issues with _download .SH "AUTHOR" .IX Header "AUTHOR" brian d foy, \f(CW\*(C`\*(C'\fR .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2001\-2021, brian d foy, All Rights Reserved. .PP You may redistribute this under the same terms as Perl itself. PK@O\< CPAN::API::HOWTO.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::API::HOWTO 3" .TH CPAN::API::HOWTO 3 "2012-09-08" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::API::HOWTO \- a recipe book for programming with CPAN.pm .SH "RECIPES" .IX Header "RECIPES" All of these recipes assume that you have put \*(L"use \s-1CPAN\*(R"\s0 at the top of your program. .SS "What distribution contains a particular module?" .IX Subsection "What distribution contains a particular module?" .Vb 3 \& my $distribution = CPAN::Shell\->expand( \& "Module", "Data::UUID" \& )\->distribution()\->pretty_id(); .Ve .PP This returns a string of the form \*(L"\s-1AUTHORID/TARBALL\*(R".\s0 If you want the full path and filename to this distribution on a \s-1CPAN\s0 mirror, then it is \&\f(CW\*(C`.../authors/id/A/AU/AUTHORID/TARBALL\*(C'\fR. .SS "What modules does a particular distribution contain?" .IX Subsection "What modules does a particular distribution contain?" .Vb 4 \& CPAN::Index\->reload(); \& my @modules = CPAN::Shell\->expand( \& "Distribution", "JHI/Graph\-0.83.tar.gz" \& )\->containsmods(); .Ve .PP You may also refer to a distribution in the form A/AU/AUTHORID/TARBALL. .SH "SEE ALSO" .IX Header "SEE ALSO" the main \s-1CPAN\s0.pm documentation .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP See .SH "AUTHOR" .IX Header "AUTHOR" David Cantrell PK@O\+YҚXXPOD2::PT_BR::local::lib.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "POD2::PT_BR::local::lib 3" .TH POD2::PT_BR::local::lib 3 "2019-11-14" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" local::lib~[pt_br] \- crie e use um diretório lib/ local para módulos perl com PERL5LIB .SH "SINOPSE" .IX Header "SINOPSE" No código \- .PP .Vb 1 \& use local::lib; # configura um lib local em ~/perl5 \& \& use local::lib \*(Aq~/foo\*(Aq; # idem, mas ~/foo \& \& # Ou... \& use FindBin; \& use local::lib "$FindBin::Bin/../suporte"; # bibliotecas de suporte locais à aplicação .Ve .PP Pela linha de comando (shell) \- .PP .Vb 2 \& # Instala o LWP e suas dependências não encontradas no diretório \*(Aq~/perl5\*(Aq \& perl \-MCPAN \-Mlocal::lib \-e \*(AqCPAN::install(LWP)\*(Aq \& \& # Apenas exibe alguns comandos úteis para a shell \& $ perl \-Mlocal::lib \& export PERL_MB_OPT=\*(Aq\-\-install_base /home/username/perl5\*(Aq \& export PERL_MM_OPT=\*(AqINSTALL_BASE=/home/username/perl5\*(Aq \& export PERL5LIB=\*(Aq/home/username/perl5/lib/perl5/i386\-linux:/home/username/perl5/lib/perl5\*(Aq \& export PATH="/home/username/perl5/bin:$PATH" .Ve .SS "A técnica de 'bootstrapping'" .IX Subsection "A técnica de 'bootstrapping'" Uma forma comum de instalar o local::lib é usando o que é conhecido como técnica de \*(L"bootstrapping\*(R". É uma boa abordagem caso seu administrador de sistemas não tenha instalado o local::lib. Nesse caso, você precisará instalar o local::lib em seu diretório de usuário. .PP Caso você tenha privilégios de administrador, ainda assim deverá configurar suas variáveis de ambiente, como discutido no passo 4, abaixo. Sem elas, você ainda instalará módulos no \s-1CPAN\s0 do sistema e seus scripts Perl não utilizarão o caminho para o lib/ que você definiu com o local::lib. .PP Por padrão, o local::lib instala os módulos do \s-1CPAN\s0 e a si próprio em ~/perl5. .PP Usuários do Windows devem ler \*(L"Diferenças ao usar esse módulo em Win32\*(R". .PP 1. Baixe e descompacte o local::lib do \s-1CPAN\s0 (procure por \*(L"Download\*(R" na página do \s-1CPAN\s0 sobre o local::lib). Faça isso como um usuário comum, não como root ou administrador. Descompacte o arquivo em seu diretório de usuário ou em qualquer outro local conveniente. .PP 2. Execute isso: .PP .Vb 1 \& perl Makefile.PL \-\-bootstrap .Ve .PP Caso o sistema pergunte se deve configurar tudo que puder automaticamente, você provavelmente deve responder que sim (yes). .PP Para instalar o local::lib em um diretório que não o padrão, você precisará especificá\-lo ao chamar o bootstrap, da seguinte forma: .PP .Vb 1 \& perl Makefile.PL \-\-bootstrap=~/foo .Ve .PP 3. Execute isso: (local::lib assume que você possui o comando 'make' instalado em seu sistema) .PP .Vb 1 \& make test && make install .Ve .PP 4. Agora precisamos configurar as variáveis de ambiente apropriadas para que o Perl use nosso recém\-criado diretório lib/. Caso esteja usando bash ou outra shell Bourne, você pode fazer isso adicionando a seguinte linha em seu script de inicialização da shell: .PP .Vb 1 \& echo \*(Aqeval $(perl \-I$HOME/perl5/lib/perl5 \-Mlocal::lib)\*(Aq >>~/.bashrc .Ve .PP Caso esteja usando a shell C, pode fazer da seguinte forma: .PP .Vb 4 \& /bin/csh \& echo $SHELL \& /bin/csh \& perl \-I$HOME/perl5/lib/perl5 \-Mlocal::lib >> ~/.cshrc .Ve .PP Caso tenha passado para o bootstrap um diretório que não o padrão, você precisará indicá\-lo na chamada ao local::lib, dessa forma: .PP .Vb 1 \& echo \*(Aqeval $(perl \-I$HOME/foo/lib/perl5 \-Mlocal::lib=$HOME/foo)\*(Aq >>~/.bashrc .Ve .PP Após atualizar seu arquivo de configuração da shell, certifique-se de processá\-lo novamente para obter as modificações em sua shell atual. Shells Bourne usam \f(CW\*(C`. ~/.bashrc\*(C'\fR para isso, enquanto shells C usam \f(CW\*(C`source ~/.cshrc\*(C'\fR. .PP Se estiver em uma máquina lenta ou operando com grandes limitações de espaço em disco, você pode desativar a geração automática de manpages a partir do \s-1POD\s0 ao instalar módulos. Para isso, basta passar o argumento \&\f(CW\*(C`\-\-no\-manpages\*(C'\fR durante o bootstrap: .PP .Vb 1 \& perl Makefile.PL \-\-bootstrap \-\-no\-manpages .Ve .PP Para evitar ter que fazer vários bootstraps para vários ambientes de módulos Perl na mesma conta de usuário \- por exemplo se você usa o local::lib para desenvolver diferentes aplicativos independentes \- você pode utilizar uma única instalação bootstrap do local::lib para instalar módulos em diretórios diferentes da seguinte forma: .PP .Vb 7 \& cd ~/meudir1 \& perl \-Mlocal::lib=./ \& eval $(perl \-Mlocal::lib=./) ### Para configurar o ambiente apenas nessa shell \& printenv ### Veja que o ~/meudir1 está na PERL5LIB \& perl \-MCPAN \-e install ... ### Os módulos que quiser \& cd ../meudir2 \& ... REPITA ... .Ve .PP Para múltiplos ambientes destinados a múltiplos aplicativos, você pode precisar incluir uma versão modificada das instruções de \f(CW\*(C`use FindBin\*(C'\fR no exemplo \*(L"No código\*(R" acima. Caso tenha feito algo como o que foi descrito acima, terá um conjunto de módulos Perl em \f(CW\*(C`~/meudir1/lib\*(C'\fR. Caso tenha um script em \f(CW\*(C`~/meudir1/scripts/meuscript.pl\*(C'\fR, você precisará indicar a ele onde encontrar os módulos que instalou para ele em \f(CW\*(C`~/meudir1/lib\*(C'\fR. .PP Em \f(CW\*(C`~/meudir1/scripts/meuscript.pl\*(C'\fR: .PP .Vb 4 \& use strict; \& use warnings; \& use local::lib "$FindBin::Bin/.."; ### aponta para ~/meudir1 e o local::lib acha o lib/ \& use lib "$FindBin::Bin/../lib"; ### aponta para ~/meudir1/lib .Ve .PP Coloque isso antes de qualquer bloco \s-1BEGIN\s0 { ... } que precise dos módulos instalados. .SS "Diferenças ao usar esse módulo em Win32" .IX Subsection "Diferenças ao usar esse módulo em Win32" Para configurar as variáveis de ambiente apropriadas para sua sessão atual do \f(CW\*(C`CMD.exe\*(C'\fR, você pode fazer assim: .PP .Vb 5 \& C:\e>perl \-Mlocal::lib \& set PERL_MB_OPT=\-\-install_base C:\eDOCUME~1\eADMINI~1\eperl5 \& set PERL_MM_OPT=INSTALL_BASE=C:\eDOCUME~1\eADMINI~1\eperl5 \& set PERL5LIB=C:\eDOCUME~1\eADMINI~1\eperl5\elib\eperl5;C:\eDOCUME~1\eADMINI~1\eperl5\elib\eperl5\eMSWin32\-x86\-multi\-thread \& set PATH=C:\eDOCUME~1\eADMINI~1\eperl5\ebin;%PATH% \& \& ### Para configurar o ambiente apenas dessa shell \& C:\e>perl \-Mlocal::lib > %TEMP%\etmp.bat && %TEMP%\etmp.bat && del %TEMP%\etemp.bat \& ### em vez de $(perl \-Mlocal::lib=./) .Ve .PP Caso queira que as configurações do ambiente persistam, você precisará adicioná\-las em Painel de Controle \-> Sistema, ou usar o App::local::lib::Win32Helper. .PP O \*(L"~\*(R" é transformado no diretório do perfil do usuário (o diretório com o nome do usuário dentro de \*(L"Documents and Settings\*(R" (Windows \s-1XP\s0 ou anterior) ou \*(L"Usuários\*(R" (Windows Vista e mais recentes)) a menos que \f(CW$ENV\fR{\s-1HOME\s0} exista. Após isso, o nome do diretório é encurtado e os subdiretórios são criados (o que significa que o diretório deve existir). .SH "MOTIVAÇÃO" .IX Header "MOTIVAÇÃO" A versão de um pacote Perl na sua máquina nem sempre é a que você precisa. Obviamente, a melhor coisa a fazer seria atualizá\-la para a versão desejada. No entanto, você pode estar em uma situação que o impede de fazer isso. Talvez você não tenha privilégios de administrador do sistema; ou talvez esteja usando um sistema de gerenciamento de pacotes como o do Debian, e ainda não exista um pacote disponível na versão desejada. .PP local::lib resolve esse problema possibilitando a criação de seu próprio diretório de pacotes Perl obtidos do \s-1CPAN\s0 (em sistemas multi\-usuário, isso normalmente fica dentro do diretório de seu usuário). A instalação do Perl no sistema permanece inalterada; você simplesmente chama o Perl com opções especiais para que ele use os pacotes em seu diretório local em vez dos pacotes do sistema. O local::lib organiza as coisas para que versões dos pacotes Perl instalados localmente tenham precedência sobre as do sistema. .PP Caso esteja usando um sistema de gerenciamento de pacote (como em sistemas Debian), não precisará se preocupar com conflitos entre o Debian e o \s-1CPAN.\s0 Sua versão local dos pacotes será instalada em um diretório completamente diferente das versões instaladas pelo gerenciador de pacotes do sistema. .SH "DESCRIÇÃO" .IX Header "DESCRIÇÃO" Este módulo oferece uma forma rápida e conveniente para criar um repositório de módulos locais ao usuário, dentro do diretório do mesmo. Ele também monta e exibe para o usuário uma lista de variáveis de ambiente utilizando a sintaxe da shell atual do usuário (conforme especificado pela variável de ambiente \f(CW\*(C`SHELL\*(C'\fR), pronta para ser adicionada diretamente no arquivo de configuração da shell. .PP Generalizando, o local::lib permite a criação e uso de um diretório contendo módulos Perl fora do \f(CW@INC\fR do Perl. Isso facilita a produção de aplicações com uma versão específica de determinado módulo, ou coleção de módulos. Também é útil quando o mantenedor de um módulo não aplicou determinado patch que você precisa para seu aplicativo. .PP Durante o \f(CW\*(C`import\*(C'\fR, o local::lib define valores apropriados para as seguintes variáveis de ambiente: .IP "\s-1PERL_MB_OPT\s0" 4 .IX Item "PERL_MB_OPT" .PD 0 .IP "\s-1PERL_MM_OPT\s0" 4 .IX Item "PERL_MM_OPT" .IP "\s-1PERL5LIB\s0" 4 .IX Item "PERL5LIB" .IP "\s-1PATH\s0" 4 .IX Item "PATH" .PD valores serão anexados ao \s-1PATH,\s0 em vez de substituí\-lo. .PP Esses valores são então disponibilizados para referência por qualquer outro código após o \f(CW\*(C`import\*(C'\fR. .SH "CRIANDO UM CONJUNTO AUTO-CONTIDO DE MÓDULOS" .IX Header "CRIANDO UM CONJUNTO AUTO-CONTIDO DE MÓDULOS" Veja lib::core::only para uma maneira de fazer isso \- mas note que há uma série de ressalvas na abordagem, e a melhor forma é sempre fazer o 'build' contra uma versão limpa do perl (i.e. com 'site' e 'vendor' o mais vazios possível). .SH "MÉTODOS" .IX Header "MÉTODOS" .SS "ensure_dir_structure_for" .IX Subsection "ensure_dir_structure_for" .ie n .IP "Argumentos: $caminho_do_diretorio" 4 .el .IP "Argumentos: \f(CW$caminho_do_diretorio\fR" 4 .IX Item "Argumentos: $caminho_do_diretorio" .PD 0 .IP "Valor de Retorno: Nenhum" 4 .IX Item "Valor de Retorno: Nenhum" .PD .PP Tenta criar o caminho fornecido, e todos os diretórios superiores necessários. Gera uma exceção em caso de falha. .SS "print_environment_vars_for" .IX Subsection "print_environment_vars_for" .ie n .IP "Argumentos: $caminho_do_diretorio" 4 .el .IP "Argumentos: \f(CW$caminho_do_diretorio\fR" 4 .IX Item "Argumentos: $caminho_do_diretorio" .PD 0 .IP "Valor de Retorno: Nenhum" 4 .IX Item "Valor de Retorno: Nenhum" .PD .PP Exibe na saída padrão as variáveis listadas acima, devidamente ajustadas para utilizar o caminho fornecido como diretório base. .SS "build_environment_vars_for" .IX Subsection "build_environment_vars_for" .ie n .IP "Argumentos: $caminho_do_diretorio, $interpolar" 4 .el .IP "Argumentos: \f(CW$caminho_do_diretorio\fR, \f(CW$interpolar\fR" 4 .IX Item "Argumentos: $caminho_do_diretorio, $interpolar" .PD 0 .ie n .IP "Valor de Retorno: %variaveis_de_ambiente" 4 .el .IP "Valor de Retorno: \f(CW%variaveis_de_ambiente\fR" 4 .IX Item "Valor de Retorno: %variaveis_de_ambiente" .PD .PP Retorna hash contendo as variáveis de ambiente listadas acima, devidamente ajustadas para utilizar o caminho fornecido como diretório base. .SS "setup_env_hash_for" .IX Subsection "setup_env_hash_for" .ie n .IP "Argumentos: $caminho_do_diretorio" 4 .el .IP "Argumentos: \f(CW$caminho_do_diretorio\fR" 4 .IX Item "Argumentos: $caminho_do_diretorio" .PD 0 .IP "Valor de Retorno: Nenhum" 4 .IX Item "Valor de Retorno: Nenhum" .PD .PP Constrói as chaves no \f(CW%ENV\fR para o caminho fornecido, chamando \&\f(CW\*(C`build_environment_vars_for\*(C'\fR. .SS "install_base_perl_path" .IX Subsection "install_base_perl_path" .ie n .IP "Argumentos: $caminho_do_diretorio" 4 .el .IP "Argumentos: \f(CW$caminho_do_diretorio\fR" 4 .IX Item "Argumentos: $caminho_do_diretorio" .PD 0 .ie n .IP "Valor de Retorno: $caminho_base_de_instalacao" 4 .el .IP "Valor de Retorno: \f(CW$caminho_base_de_instalacao\fR" 4 .IX Item "Valor de Retorno: $caminho_base_de_instalacao" .PD .PP Retorna um caminho de diretório indicando onde instalar os módulos Perl para essa instalação local de bibliotecas. Adiciona os diretórios \f(CW\*(C`lib\*(C'\fR e \f(CW\*(C`perl5\*(C'\fR ao final do caminho fornecido. .SS "install_base_arch_path" .IX Subsection "install_base_arch_path" .ie n .IP "Argumentos: $caminho_do_diretorio" 4 .el .IP "Argumentos: \f(CW$caminho_do_diretorio\fR" 4 .IX Item "Argumentos: $caminho_do_diretorio" .PD 0 .ie n .IP "Valor de Retorno: $caminho_base_de_instalacao_arch" 4 .el .IP "Valor de Retorno: \f(CW$caminho_base_de_instalacao_arch\fR" 4 .IX Item "Valor de Retorno: $caminho_base_de_instalacao_arch" .PD .PP Retorna um caminho de diretório indicando onde instalar os módulos Perl de arquiteturas específicas para essa instalação local de bibliotecas. Baseia-se no valor de retorno do método \*(L"install_base_perl_path\*(R", adicionando o valor de \f(CW$Config{archname}\fR. .SS "install_base_bin_path" .IX Subsection "install_base_bin_path" .ie n .IP "Argumentos: $caminho_do_diretorio" 4 .el .IP "Argumentos: \f(CW$caminho_do_diretorio\fR" 4 .IX Item "Argumentos: $caminho_do_diretorio" .PD 0 .ie n .IP "Valor de Retorno: $caminho_base_de_instalacao_bin" 4 .el .IP "Valor de Retorno: \f(CW$caminho_base_de_instalacao_bin\fR" 4 .IX Item "Valor de Retorno: $caminho_base_de_instalacao_bin" .PD .PP Retorna um caminho de diretório indicando onde instalar programas executáveis para essa instalação local de bibliotecas. Baseia-se no valor de retorno do método \*(L"install_base_perl_path\*(R", adicionando o diretório \f(CW\*(C`bin\*(C'\fR. .SS "resolve_empty_path" .IX Subsection "resolve_empty_path" .ie n .IP "Argumentos: $caminho_do_diretorio" 4 .el .IP "Argumentos: \f(CW$caminho_do_diretorio\fR" 4 .IX Item "Argumentos: $caminho_do_diretorio" .PD 0 .ie n .IP "Valor de Retorno: $caminho_base_de_instalacao" 4 .el .IP "Valor de Retorno: \f(CW$caminho_base_de_instalacao\fR" 4 .IX Item "Valor de Retorno: $caminho_base_de_instalacao" .PD .PP Cria e retorna o caminho de diretório raiz em que a instalação local de módulos deve ser feita. O padrão é \f(CW\*(C`~/perl5\*(C'\fR. .SS "resolve_home_path" .IX Subsection "resolve_home_path" .ie n .IP "Argumentos: $caminho_do_diretorio" 4 .el .IP "Argumentos: \f(CW$caminho_do_diretorio\fR" 4 .IX Item "Argumentos: $caminho_do_diretorio" .PD 0 .ie n .IP "Valor de Retorno: $caminho_para_home" 4 .el .IP "Valor de Retorno: \f(CW$caminho_para_home\fR" 4 .IX Item "Valor de Retorno: $caminho_para_home" .PD .PP Procura pelo diretório padrão (home) do usuário. Gera uma exceção caso não encontre resultado definitivo. .SS "resolve_relative_path" .IX Subsection "resolve_relative_path" .ie n .IP "Argumentos: $caminho_do_diretorio" 4 .el .IP "Argumentos: \f(CW$caminho_do_diretorio\fR" 4 .IX Item "Argumentos: $caminho_do_diretorio" .PD 0 .ie n .IP "Valor de Retorno: $caminho_absoluto" 4 .el .IP "Valor de Retorno: \f(CW$caminho_absoluto\fR" 4 .IX Item "Valor de Retorno: $caminho_absoluto" .PD .PP Transforma o caminho fornecido em um caminho absoluto. .SS "resolve_path" .IX Subsection "resolve_path" .ie n .IP "Argumentos: $caminho_do_diretorio" 4 .el .IP "Argumentos: \f(CW$caminho_do_diretorio\fR" 4 .IX Item "Argumentos: $caminho_do_diretorio" .PD 0 .ie n .IP "Valor de Retorno: $caminho_absoluto" 4 .el .IP "Valor de Retorno: \f(CW$caminho_absoluto\fR" 4 .IX Item "Valor de Retorno: $caminho_absoluto" .PD .PP Invoca os seguintes métodos em sequência, passando o resultado do método anterior para o seguinte, na tentativa de descobrir onde configurar o ambiente para a instalação local de bibliotecas: \*(L"resolve_empty_path\*(R", \&\*(L"resolve_home_path\*(R", \*(L"resolve_relative_path\*(R". Passa o caminho de diretório fornecido para \*(L"resolve_empty_path\*(R" que retorna um resultado que é passado para \*(L"resolve_home_path\*(R", que então tem seu resultado passado para \*(L"resolve_relative_path\*(R". O resultado dessa chamada final é então retornado pelo \*(L"resolve_path\*(R". .SH "UM AVISO SOBRE UNINST=1" .IX Header "UM AVISO SOBRE UNINST=1" Tenha cuidado ao usar o local::lib em conjunto com \*(L"make install UNINST=1\*(R". A idéia dessa opção é desinstalar a versão anterior de um módulo antes de instalar a mais recente. No entanto ela não possui uma verificação de segurança de que a versão antiga e a nova referem-se ao mesmo diretório. Usada em combinação com o local::lib, você pode potencialmente apagar uma versão globalmente acessível de um módulo e instalar a versão mais nova no diretório local. Apenas utilize \*(L"make install UNINST=1\*(R" junto com o local::lib se você entende essas possíveis consequências. .SH "LIMITAÇÕES" .IX Header "LIMITAÇÕES" As ferramentas auxiliares do perl não conseguem lidar com nomes de diretórios contendo espaços, então não é possível fazer seu bootstrap do local::lib em um diretório com espaços. O que você pode fazer é mover seu local::lib para um diretório com espaços \fBapós\fR ter instalado todos os módulos dentro dele. Mas esteja ciente que você não poderá atualizar ou instalar outros módulos do \s-1CPAN\s0 nesse diretório local após a mudança. .PP A detecção da shell é relativamente básica. Neste momento, qualquer coisa com csh no nome será tratada como a C shell ou compatível, e todo o resto será tratado como Bourne, exceto em sistemas Win32. Caso a variável de ambiente \f(CW\*(C`SHELL\*(C'\fR não esteja disponível, assumiremos tratar-se de uma shell compatível com a Bourne. .PP A técnica de bootstrap é um hack e usará o \s-1CPAN\s0.pm para o ExtUtils::MakeMaker mesmo que você tenha o \s-1CPANPLUS\s0 instalado. .PP Destrói qualquer valor pré\-existente nas variáveis de ambiente \s-1PERL5LIB, PERL_MM_OPT\s0 e \s-1PERL_MB_OPT.\s0 .PP Provavelmente deveria auto-configurar o \s-1CPAN\s0 caso isso ainda não tenha sido feito. .PP Correções (patches) são muito bem-vindos para quaisquer dos itens acima. .PP Em sistemas Win32, não há uma forma de escrever no registro as variáveis de ambiente criadas, para que elas persistam a uma reinicialização. .SH "SOLUÇÃO DE PROBLEMAS" .IX Header "SOLUÇÃO DE PROBLEMAS" Se você configurou o local::lib para instalar módulos do \s-1CPAN\s0 em algum lugar do seu 'home', e mais tarde tentou instalar um módulo fazendo \f(CW\*(C`cpan \-i Foo::Bar\*(C'\fR, mas ele falhou com um erro como: \f(CW\*(C`Warning: You do not have permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64\-linux at /usr/lib64/perl5/5.8.8/Foo/Bar.pm\*(C'\fR e em algum lugar no seu log de instalação houver um erro dizendo \f(CW\*(C`\*(AqINSTALL_BASE\*(Aq is not a known MakeMaker parameter name\*(C'\fR, então você de alguma forma perdeu seu ExtUtils::MakeMaker atualizado. .PP Para remediar a situação, execute novamente o procedimento de bootstrap descrito acima. .PP Então, execute \f(CW\*(C`rm \-r ~/.cpan/build/Foo\-Bar*\*(C'\fR .PP Finalmente, execute novamente o \f(CW\*(C`cpan \-i Foo::Bar\*(C'\fR e ele deve instalar sem problemas. .SH "AMBIENTE" .IX Header "AMBIENTE" .IP "\s-1SHELL\s0" 4 .IX Item "SHELL" .PD 0 .IP "\s-1COMSPEC\s0" 4 .IX Item "COMSPEC" .PD O local::lib procura pela variável de ambiente \f(CW\*(C`SHELL\*(C'\fR do usuário ao processar e exibir os comandos a serem adicionados no arquivo de configuração da shell. .Sp Em sistemas Win32, \f(CW\*(C`COMSPEC\*(C'\fR também será examinado. .SH "SUPORTE" .IX Header "SUPORTE" \&\s-1IRC:\s0 .PP .Vb 1 \& Acesse #local\-lib em irc.perl.org. .Ve .SH "AUTOR DA TRADUÇÃO" .IX Header "AUTOR DA TRADUÇÃO" Breno G. de Oliveira, \f(CW\*(C`\*(C'\fR, após ter perdido uma aposta para o Getty durante a Copa de 2010. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2007 \- 2010 \*(L"\s-1AUTHOR\*(R"\s0 in local::lib e \*(L"\s-1CONTRIBUTORS\*(R"\s0 in local::lib do local::lib como listados em local::lib. .SH "LICENÇA" .IX Header "LICENÇA" Esta biblioteca é software livre e pode ser distribuída sob os mesmo termos do perl. PK@O\UeBJBJ Switch.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Switch 3" .TH Switch 3 "2014-03-18" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Switch \- A switch statement for Perl, do not use if you can use given/when .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Switch; \& \& switch ($val) { \& case 1 { print "number 1" } \& case "a" { print "string a" } \& case [1..10,42] { print "number in list" } \& case (\e@array) { print "number in list" } \& case /\ew+/ { print "pattern" } \& case qr/\ew+/ { print "pattern" } \& case (\e%hash) { print "entry in hash" } \& case (\e&sub) { print "arg to subroutine" } \& else { print "previous case not true" } \& } .Ve .SH "BACKGROUND" .IX Header "BACKGROUND" [Skip ahead to \*(L"\s-1DESCRIPTION\*(R"\s0 if you don't care about the whys and wherefores of this control structure] .PP In seeking to devise a \*(L"Swiss Army\*(R" case mechanism suitable for Perl, it is useful to generalize this notion of distributed conditional testing as far as possible. Specifically, the concept of \*(L"matching\*(R" between the switch value and the various case values need not be restricted to numeric (or string or referential) equality, as it is in other languages. Indeed, as Table 1 illustrates, Perl offers at least eighteen different ways in which two values could generate a match. .PP .Vb 1 \& Table 1: Matching a switch value ($s) with a case value ($c) \& \& Switch Case Type of Match Implied Matching Code \& Value Value \& ====== ===== ===================== ============= \& \& number same numeric or referential match if $s == $c; \& or ref equality \& \& object method result of method call match if $s\->$c(); \& ref name match if defined $s\->$c(); \& or ref \& \& other other string equality match if $s eq $c; \& non\-ref non\-ref \& scalar scalar \& \& string regexp pattern match match if $s =~ /$c/; \& \& array scalar array entry existence match if 0<=$c && $c<@$s; \& ref array entry definition match if defined $s\->[$c]; \& array entry truth match if $s\->[$c]; \& \& array array array intersection match if intersects(@$s, @$c); \& ref ref (apply this table to \& all pairs of elements \& $s\->[$i] and \& $c\->[$j]) \& \& array regexp array grep match if grep /$c/, @$s; \& ref \& \& hash scalar hash entry existence match if exists $s\->{$c}; \& ref hash entry definition match if defined $s\->{$c}; \& hash entry truth match if $s\->{$c}; \& \& hash regexp hash grep match if grep /$c/, keys %$s; \& ref \& \& sub scalar return value defn match if defined $s\->($c); \& ref return value truth match if $s\->($c); \& \& sub array return value defn match if defined $s\->(@$c); \& ref ref return value truth match if $s\->(@$c); .Ve .PP In reality, Table 1 covers 31 alternatives, because only the equality and intersection tests are commutative; in all other cases, the roles of the \f(CW$s\fR and \f(CW$c\fR variables could be reversed to produce a different test. For example, instead of testing a single hash for the existence of a series of keys (\f(CW\*(C`match if exists $s\->{$c}\*(C'\fR), one could test for the existence of a single key in a series of hashes (\f(CW\*(C`match if exists $c\->{$s}\*(C'\fR). .SH "DESCRIPTION" .IX Header "DESCRIPTION" The Switch.pm module implements a generalized case mechanism that covers most (but not all) of the numerous possible combinations of switch and case values described above. .PP The module augments the standard Perl syntax with two new control statements: \f(CW\*(C`switch\*(C'\fR and \f(CW\*(C`case\*(C'\fR. The \f(CW\*(C`switch\*(C'\fR statement takes a single scalar argument of any type, specified in parentheses. \&\f(CW\*(C`switch\*(C'\fR stores this value as the current switch value in a (localized) control variable. The value is followed by a block which may contain one or more Perl statements (including the \f(CW\*(C`case\*(C'\fR statement described below). The block is unconditionally executed once the switch value has been cached. .PP A \f(CW\*(C`case\*(C'\fR statement takes a single scalar argument (in mandatory parentheses if it's a variable; otherwise the parens are optional) and selects the appropriate type of matching between that argument and the current switch value. The type of matching used is determined by the respective types of the switch value and the \f(CW\*(C`case\*(C'\fR argument, as specified in Table 1. If the match is successful, the mandatory block associated with the \f(CW\*(C`case\*(C'\fR statement is executed. .PP In most other respects, the \f(CW\*(C`case\*(C'\fR statement is semantically identical to an \f(CW\*(C`if\*(C'\fR statement. For example, it can be followed by an \f(CW\*(C`else\*(C'\fR clause, and can be used as a postfix statement qualifier. .PP However, when a \f(CW\*(C`case\*(C'\fR block has been executed control is automatically transferred to the statement after the immediately enclosing \f(CW\*(C`switch\*(C'\fR block, rather than to the next statement within the block. In other words, the success of any \f(CW\*(C`case\*(C'\fR statement prevents other cases in the same scope from executing. But see \*(L"Allowing fall-through\*(R" below. .PP Together these two new statements provide a fully generalized case mechanism: .PP .Vb 1 \& use Switch; \& \& # AND LATER... \& \& %special = ( woohoo => 1, d\*(Aqoh => 1 ); \& \& while (<>) { \& chomp; \& switch ($_) { \& case (%special) { print "homer\en"; } # if $special{$_} \& case /[a\-z]/i { print "alpha\en"; } # if $_ =~ /a\-z/i \& case [1..9] { print "small num\en"; } # if $_ in [1..9] \& case { $_[0] >= 10 } { print "big num\en"; } # if $_ >= 10 \& print "must be punctuation\en" case /\eW/; # if $_ ~= /\eW/ \& } \& } .Ve .PP Note that \f(CW\*(C`switch\*(C'\fRes can be nested within \f(CW\*(C`case\*(C'\fR (or any other) blocks, and a series of \f(CW\*(C`case\*(C'\fR statements can try different types of matches \&\*(-- hash membership, pattern match, array intersection, simple equality, etc. \*(-- against the same switch value. .PP The use of intersection tests against an array reference is particularly useful for aggregating integral cases: .PP .Vb 8 \& sub classify_digit \& { \& switch ($_[0]) { case 0 { return \*(Aqzero\*(Aq } \& case [2,4,6,8] { return \*(Aqeven\*(Aq } \& case [1,3,5,7,9] { return \*(Aqodd\*(Aq } \& case /[A\-F]/i { return \*(Aqhex\*(Aq } \& } \& } .Ve .SS "Allowing fall-through" .IX Subsection "Allowing fall-through" Fall-though (trying another case after one has already succeeded) is usually a Bad Idea in a switch statement. However, this is Perl, not a police state, so there \fIis\fR a way to do it, if you must. .PP If a \f(CW\*(C`case\*(C'\fR block executes an untargeted \f(CW\*(C`next\*(C'\fR, control is immediately transferred to the statement \fIafter\fR the \f(CW\*(C`case\*(C'\fR statement (i.e. usually another case), rather than out of the surrounding \&\f(CW\*(C`switch\*(C'\fR block. .PP For example: .PP .Vb 7 \& switch ($val) { \& case 1 { handle_num_1(); next } # and try next case... \& case "1" { handle_str_1(); next } # and try next case... \& case [0..9] { handle_num_any(); } # and we\*(Aqre done \& case /\ed/ { handle_dig_any(); next } # and try next case... \& case /.*/ { handle_str_any(); next } # and try next case... \& } .Ve .PP If \f(CW$val\fR held the number \f(CW1\fR, the above \f(CW\*(C`switch\*(C'\fR block would call the first three \f(CW\*(C`handle_...\*(C'\fR subroutines, jumping to the next case test each time it encountered a \f(CW\*(C`next\*(C'\fR. After the third \f(CW\*(C`case\*(C'\fR block was executed, control would jump to the end of the enclosing \&\f(CW\*(C`switch\*(C'\fR block. .PP On the other hand, if \f(CW$val\fR held \f(CW10\fR, then only the last two \f(CW\*(C`handle_...\*(C'\fR subroutines would be called. .PP Note that this mechanism allows the notion of \fIconditional fall-through\fR. For example: .PP .Vb 4 \& switch ($val) { \& case [0..9] { handle_num_any(); next if $val < 7; } \& case /\ed/ { handle_dig_any(); } \& } .Ve .PP If an untargeted \f(CW\*(C`last\*(C'\fR statement is executed in a case block, this immediately transfers control out of the enclosing \f(CW\*(C`switch\*(C'\fR block (in other words, there is an implicit \f(CW\*(C`last\*(C'\fR at the end of each normal \f(CW\*(C`case\*(C'\fR block). Thus the previous example could also have been written: .PP .Vb 4 \& switch ($val) { \& case [0..9] { handle_num_any(); last if $val >= 7; next; } \& case /\ed/ { handle_dig_any(); } \& } .Ve .SS "Automating fall-through" .IX Subsection "Automating fall-through" In situations where case fall-through should be the norm, rather than an exception, an endless succession of terminal \f(CW\*(C`next\*(C'\fRs is tedious and ugly. Hence, it is possible to reverse the default behaviour by specifying the string \*(L"fallthrough\*(R" when importing the module. For example, the following code is equivalent to the first example in \*(L"Allowing fall-through\*(R": .PP .Vb 1 \& use Switch \*(Aqfallthrough\*(Aq; \& \& switch ($val) { \& case 1 { handle_num_1(); } \& case "1" { handle_str_1(); } \& case [0..9] { handle_num_any(); last } \& case /\ed/ { handle_dig_any(); } \& case /.*/ { handle_str_any(); } \& } .Ve .PP Note the explicit use of a \f(CW\*(C`last\*(C'\fR to preserve the non-fall-through behaviour of the third case. .SS "Alternative syntax" .IX Subsection "Alternative syntax" Perl 6 will provide a built-in switch statement with essentially the same semantics as those offered by Switch.pm, but with a different pair of keywords. In Perl 6 \f(CW\*(C`switch\*(C'\fR will be spelled \f(CW\*(C`given\*(C'\fR, and \&\f(CW\*(C`case\*(C'\fR will be pronounced \f(CW\*(C`when\*(C'\fR. In addition, the \f(CW\*(C`when\*(C'\fR statement will not require switch or case values to be parenthesized. .PP This future syntax is also (largely) available via the Switch.pm module, by importing it with the argument \f(CW"Perl6"\fR. For example: .PP .Vb 1 \& use Switch \*(AqPerl6\*(Aq; \& \& given ($val) { \& when 1 { handle_num_1(); } \& when ($str1) { handle_str_1(); } \& when [0..9] { handle_num_any(); last } \& when /\ed/ { handle_dig_any(); } \& when /.*/ { handle_str_any(); } \& default { handle anything else; } \& } .Ve .PP Note that scalars still need to be parenthesized, since they would be ambiguous in Perl 5. .PP Note too that you can mix and match both syntaxes by importing the module with: .PP .Vb 1 \& use Switch \*(AqPerl5\*(Aq, \*(AqPerl6\*(Aq; .Ve .SS "Higher-order Operations" .IX Subsection "Higher-order Operations" One situation in which \f(CW\*(C`switch\*(C'\fR and \f(CW\*(C`case\*(C'\fR do not provide a good substitute for a cascaded \f(CW\*(C`if\*(C'\fR, is where a switch value needs to be tested against a series of conditions. For example: .PP .Vb 11 \& sub beverage { \& switch (shift) { \& case { $_[0] < 10 } { return \*(Aqmilk\*(Aq } \& case { $_[0] < 20 } { return \*(Aqcoke\*(Aq } \& case { $_[0] < 30 } { return \*(Aqbeer\*(Aq } \& case { $_[0] < 40 } { return \*(Aqwine\*(Aq } \& case { $_[0] < 50 } { return \*(Aqmalt\*(Aq } \& case { $_[0] < 60 } { return \*(AqMoet\*(Aq } \& else { return \*(Aqmilk\*(Aq } \& } \& } .Ve .PP (This is equivalent to writing \f(CW\*(C`case (sub { $_[0] < 10 })\*(C'\fR, etc.; \f(CW$_[0]\fR is the argument to the anonymous subroutine.) .PP The need to specify each condition as a subroutine block is tiresome. To overcome this, when importing Switch.pm, a special \*(L"placeholder\*(R" subroutine named \f(CW\*(C`_\|_\*(C'\fR [sic] may also be imported. This subroutine converts (almost) any expression in which it appears to a reference to a higher-order function. That is, the expression: .PP .Vb 1 \& use Switch \*(Aq_\|_\*(Aq; \& \& _\|_ < 2 .Ve .PP is equivalent to: .PP .Vb 1 \& sub { $_[0] < 2 } .Ve .PP With \f(CW\*(C`_\|_\*(C'\fR, the previous ugly case statements can be rewritten: .PP .Vb 7 \& case _\|_ < 10 { return \*(Aqmilk\*(Aq } \& case _\|_ < 20 { return \*(Aqcoke\*(Aq } \& case _\|_ < 30 { return \*(Aqbeer\*(Aq } \& case _\|_ < 40 { return \*(Aqwine\*(Aq } \& case _\|_ < 50 { return \*(Aqmalt\*(Aq } \& case _\|_ < 60 { return \*(AqMoet\*(Aq } \& else { return \*(Aqmilk\*(Aq } .Ve .PP The \f(CW\*(C`_\|_\*(C'\fR subroutine makes extensive use of operator overloading to perform its magic. All operations involving _\|_ are overloaded to produce an anonymous subroutine that implements a lazy version of the original operation. .PP The only problem is that operator overloading does not allow the boolean operators \f(CW\*(C`&&\*(C'\fR and \f(CW\*(C`||\*(C'\fR to be overloaded. So a case statement like this: .PP .Vb 1 \& case 0 <= _\|_ && _\|_ < 10 { return \*(Aqdigit\*(Aq } .Ve .PP doesn't act as expected, because when it is executed, it constructs two higher order subroutines and then treats the two resulting references as arguments to \f(CW\*(C`&&\*(C'\fR: .PP .Vb 1 \& sub { 0 <= $_[0] } && sub { $_[0] < 10 } .Ve .PP This boolean expression is inevitably true, since both references are non-false. Fortunately, the overloaded \f(CW\*(Aqbool\*(Aq\fR operator catches this situation and flags it as an error. .SH "DEPENDENCIES" .IX Header "DEPENDENCIES" The module is implemented using Filter::Util::Call and Text::Balanced and requires both these modules to be installed. .SH "AUTHOR" .IX Header "AUTHOR" Damian Conway (damian@conway.org). This module is now maintained by Alexandr Ciornii (alexchorny@gmail.com). Previously was maintained by Rafael Garcia-Suarez and perl5 porters. .SH "BUGS" .IX Header "BUGS" There are undoubtedly serious bugs lurking somewhere in code this funky :\-) Bug reports and other feedback are most welcome. .PP May create syntax errors in other parts of code. .PP On perl 5.10.x may cause syntax error if \*(L"case\*(R" is present inside heredoc. .PP In general, use given/when instead. It were introduced in perl 5.10.0. Perl 5.10.0 was released in 2007. .SH "LIMITATIONS" .IX Header "LIMITATIONS" Due to the heuristic nature of Switch.pm's source parsing, the presence of regexes with embedded newlines that are specified with raw \f(CW\*(C`/.../\*(C'\fR delimiters and don't have a modifier \f(CW\*(C`//x\*(C'\fR are indistinguishable from code chunks beginning with the division operator \f(CW\*(C`/\*(C'\fR. As a workaround you must use \f(CW\*(C`m/.../\*(C'\fR or \f(CW\*(C`m?...?\*(C'\fR for such patterns. Also, the presence of regexes specified with raw \f(CW\*(C`?...?\*(C'\fR delimiters may cause mysterious errors. The workaround is to use \f(CW\*(C`m?...?\*(C'\fR instead. .PP Due to the way source filters work in Perl, you can't use Switch inside an string \f(CW\*(C`eval\*(C'\fR. .PP May not work if sub prototypes are used (RT#33988). .PP Regex captures in when are not available to code. .PP If your source file is longer then 1 million characters and you have a switch statement that crosses the 1 million (or 2 million, etc.) character boundary you will get mysterious errors. The workaround is to use smaller source files. .SH "COPYRIGHT" .IX Header "COPYRIGHT" .Vb 3 \& Copyright (c) 1997\-2008, Damian Conway. All Rights Reserved. \& This module is free software. It may be used, redistributed \& and/or modified under the same terms as Perl itself. .Ve PK@O\E4nnHTTP::Tiny.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "HTTP::Tiny 3" .TH HTTP::Tiny 3 "2023-07-11" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" HTTP::Tiny \- A small, simple, correct HTTP/1.1 client .SH "VERSION" .IX Header "VERSION" version 0.088 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use HTTP::Tiny; \& \& my $response = HTTP::Tiny\->new\->get(\*(Aqhttp://example.com/\*(Aq); \& \& die "Failed!\en" unless $response\->{success}; \& \& print "$response\->{status} $response\->{reason}\en"; \& \& while (my ($k, $v) = each %{$response\->{headers}}) { \& for (ref $v eq \*(AqARRAY\*(Aq ? @$v : $v) { \& print "$k: $_\en"; \& } \& } \& \& print $response\->{content} if length $response\->{content}; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is a very simple \s-1HTTP/1.1\s0 client, designed for doing simple requests without the overhead of a large framework like LWP::UserAgent. .PP It is more correct and more complete than HTTP::Lite. It supports proxies and redirection. It also correctly resumes after \s-1EINTR.\s0 .PP If IO::Socket::IP 0.25 or later is installed, HTTP::Tiny will use it instead of IO::Socket::INET for transparent support for both IPv4 and IPv6. .PP Cookie support requires HTTP::CookieJar or an equivalent class. .SH "METHODS" .IX Header "METHODS" .SS "new" .IX Subsection "new" .Vb 1 \& $http = HTTP::Tiny\->new( %attributes ); .Ve .PP This constructor returns a new HTTP::Tiny object. Valid attributes include: .IP "\(bu" 4 \&\f(CW\*(C`agent\*(C'\fR — A user-agent string (defaults to 'HTTP\-Tiny/$VERSION'). If \f(CW\*(C`agent\*(C'\fR — ends in a space character, the default user-agent string is appended. .IP "\(bu" 4 \&\f(CW\*(C`cookie_jar\*(C'\fR — An instance of HTTP::CookieJar — or equivalent class that supports the \f(CW\*(C`add\*(C'\fR and \f(CW\*(C`cookie_header\*(C'\fR methods .IP "\(bu" 4 \&\f(CW\*(C`default_headers\*(C'\fR — A hashref of default headers to apply to requests .IP "\(bu" 4 \&\f(CW\*(C`local_address\*(C'\fR — The local \s-1IP\s0 address to bind to .IP "\(bu" 4 \&\f(CW\*(C`keep_alive\*(C'\fR — Whether to reuse the last connection (if for the same scheme, host and port) (defaults to 1) .IP "\(bu" 4 \&\f(CW\*(C`max_redirect\*(C'\fR — Maximum number of redirects allowed (defaults to 5) .IP "\(bu" 4 \&\f(CW\*(C`max_size\*(C'\fR — Maximum response size in bytes (only when not using a data callback). If defined, requests with responses larger than this will return a 599 status code. .IP "\(bu" 4 \&\f(CW\*(C`http_proxy\*(C'\fR — \s-1URL\s0 of a proxy server to use for \s-1HTTP\s0 connections (default is \f(CW$ENV{http_proxy}\fR — if set) .IP "\(bu" 4 \&\f(CW\*(C`https_proxy\*(C'\fR — \s-1URL\s0 of a proxy server to use for \s-1HTTPS\s0 connections (default is \f(CW$ENV{https_proxy}\fR — if set) .IP "\(bu" 4 \&\f(CW\*(C`proxy\*(C'\fR — \s-1URL\s0 of a generic proxy server for both \s-1HTTP\s0 and \s-1HTTPS\s0 connections (default is \f(CW$ENV{all_proxy}\fR — if set) .IP "\(bu" 4 \&\f(CW\*(C`no_proxy\*(C'\fR — List of domain suffixes that should not be proxied. Must be a comma-separated string or an array reference. (default is \f(CW$ENV{no_proxy}\fR —) .IP "\(bu" 4 \&\f(CW\*(C`timeout\*(C'\fR — Request timeout in seconds (default is 60) If a socket open, read or write takes longer than the timeout, the request response status code will be 599. .IP "\(bu" 4 \&\f(CW\*(C`verify_SSL\*(C'\fR — A boolean that indicates whether to validate the \s-1TLS/SSL\s0 certificate of an \f(CW\*(C`https\*(C'\fR — connection (default is true). Changed from false to true in version 0.083. .IP "\(bu" 4 \&\f(CW\*(C`SSL_options\*(C'\fR — A hashref of \f(CW\*(C`SSL_*\*(C'\fR — options to pass through to IO::Socket::SSL .IP "\(bu" 4 \&\f(CW$ENV{PERL_HTTP_TINY_SSL_INSECURE_BY_DEFAULT}\fR \- Changes the default certificate verification behavior to not check server identity if set to 1. Only effective if \f(CW\*(C`verify_SSL\*(C'\fR is not set. Added in version 0.083. .PP An accessor/mutator method exists for each attribute. .PP Passing an explicit \f(CW\*(C`undef\*(C'\fR for \f(CW\*(C`proxy\*(C'\fR, \f(CW\*(C`http_proxy\*(C'\fR or \f(CW\*(C`https_proxy\*(C'\fR will prevent getting the corresponding proxies from the environment. .PP Errors during request execution will result in a pseudo-HTTP status code of 599 and a reason of \*(L"Internal Exception\*(R". The content field in the response will contain the text of the error. .PP The \f(CW\*(C`keep_alive\*(C'\fR parameter enables a persistent connection, but only to a single destination scheme, host and port. If any connection-relevant attributes are modified via accessor, or if the process \s-1ID\s0 or thread \s-1ID\s0 change, the persistent connection will be dropped. If you want persistent connections across multiple destinations, use multiple HTTP::Tiny objects. .PP See \*(L"\s-1SSL SUPPORT\*(R"\s0 for more on the \f(CW\*(C`verify_SSL\*(C'\fR and \f(CW\*(C`SSL_options\*(C'\fR attributes. .SS "get|head|put|post|patch|delete" .IX Subsection "get|head|put|post|patch|delete" .Vb 3 \& $response = $http\->get($url); \& $response = $http\->get($url, \e%options); \& $response = $http\->head($url); .Ve .PP These methods are shorthand for calling \f(CW\*(C`request()\*(C'\fR for the given method. The \&\s-1URL\s0 must have unsafe characters escaped and international domain names encoded. See \f(CW\*(C`request()\*(C'\fR for valid options and a description of the response. .PP The \f(CW\*(C`success\*(C'\fR field of the response will be true if the status code is 2XX. .SS "post_form" .IX Subsection "post_form" .Vb 2 \& $response = $http\->post_form($url, $form_data); \& $response = $http\->post_form($url, $form_data, \e%options); .Ve .PP This method executes a \f(CW\*(C`POST\*(C'\fR request and sends the key/value pairs from a form data hash or array reference to the given \s-1URL\s0 with a \f(CW\*(C`content\-type\*(C'\fR of \&\f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR. If data is provided as an array reference, the order is preserved; if provided as a hash reference, the terms are sorted on key and value for consistency. See documentation for the \&\f(CW\*(C`www_form_urlencode\*(C'\fR method for details on the encoding. .PP The \s-1URL\s0 must have unsafe characters escaped and international domain names encoded. See \f(CW\*(C`request()\*(C'\fR for valid options and a description of the response. Any \f(CW\*(C`content\-type\*(C'\fR header or content in the options hashref will be ignored. .PP The \f(CW\*(C`success\*(C'\fR field of the response will be true if the status code is 2XX. .SS "mirror" .IX Subsection "mirror" .Vb 4 \& $response = $http\->mirror($url, $file, \e%options) \& if ( $response\->{success} ) { \& print "$file is up to date\en"; \& } .Ve .PP Executes a \f(CW\*(C`GET\*(C'\fR request for the \s-1URL\s0 and saves the response body to the file name provided. The \s-1URL\s0 must have unsafe characters escaped and international domain names encoded. If the file already exists, the request will include an \&\f(CW\*(C`If\-Modified\-Since\*(C'\fR header with the modification timestamp of the file. You may specify a different \f(CW\*(C`If\-Modified\-Since\*(C'\fR header yourself in the \f(CW\*(C`$options\->{headers}\*(C'\fR hash. .PP The \f(CW\*(C`success\*(C'\fR field of the response will be true if the status code is 2XX or if the status code is 304 (unmodified). .PP If the file was modified and the server response includes a properly formatted \f(CW\*(C`Last\-Modified\*(C'\fR header, the file modification time will be updated accordingly. .SS "request" .IX Subsection "request" .Vb 2 \& $response = $http\->request($method, $url); \& $response = $http\->request($method, $url, \e%options); .Ve .PP Executes an \s-1HTTP\s0 request of the given method type ('\s-1GET\s0', '\s-1HEAD\s0', '\s-1POST\s0', \&'\s-1PUT\s0', etc.) on the given \s-1URL.\s0 The \s-1URL\s0 must have unsafe characters escaped and international domain names encoded. .PP \&\fB\s-1NOTE\s0\fR: Method names are \fBcase-sensitive\fR per the \s-1HTTP/1.1\s0 specification. Don't use \f(CW\*(C`get\*(C'\fR when you really want \f(CW\*(C`GET\*(C'\fR. See \s-1LIMITATIONS\s0 for how this applies to redirection. .PP If the \s-1URL\s0 includes a \*(L"user:password\*(R" stanza, they will be used for Basic-style authorization headers. (Authorization headers will not be included in a redirected request.) For example: .PP .Vb 1 \& $http\->request(\*(AqGET\*(Aq, \*(Aqhttp://Aladdin:open sesame@example.com/\*(Aq); .Ve .PP If the \*(L"user:password\*(R" stanza contains reserved characters, they must be percent-escaped: .PP .Vb 1 \& $http\->request(\*(AqGET\*(Aq, \*(Aqhttp://john%40example.com:password@example.com/\*(Aq); .Ve .PP A hashref of options may be appended to modify the request. .PP Valid options are: .IP "\(bu" 4 \&\f(CW\*(C`headers\*(C'\fR — A hashref containing headers to include with the request. If the value for a header is an array reference, the header will be output multiple times with each value in the array. These headers over-write any default headers. .IP "\(bu" 4 \&\f(CW\*(C`content\*(C'\fR — A scalar to include as the body of the request \s-1OR\s0 a code reference that will be called iteratively to produce the body of the request .IP "\(bu" 4 \&\f(CW\*(C`trailer_callback\*(C'\fR — A code reference that will be called if it exists to provide a hashref of trailing headers (only used with chunked transfer-encoding) .IP "\(bu" 4 \&\f(CW\*(C`data_callback\*(C'\fR — A code reference that will be called for each chunks of the response body received. .IP "\(bu" 4 \&\f(CW\*(C`peer\*(C'\fR — Override host resolution and force all connections to go only to a specific peer address, regardless of the \s-1URL\s0 of the request. This will include any redirections! This options should be used with extreme caution (e.g. debugging or very special circumstances). It can be given as either a scalar or a code reference that will receive the hostname and whose response will be taken as the address. .PP The \f(CW\*(C`Host\*(C'\fR header is generated from the \s-1URL\s0 in accordance with \s-1RFC 2616.\s0 It is a fatal error to specify \f(CW\*(C`Host\*(C'\fR in the \f(CW\*(C`headers\*(C'\fR option. Other headers may be ignored or overwritten if necessary for transport compliance. .PP If the \f(CW\*(C`content\*(C'\fR option is a code reference, it will be called iteratively to provide the content body of the request. It should return the empty string or undef when the iterator is exhausted. .PP If the \f(CW\*(C`content\*(C'\fR option is the empty string, no \f(CW\*(C`content\-type\*(C'\fR or \&\f(CW\*(C`content\-length\*(C'\fR headers will be generated. .PP If the \f(CW\*(C`data_callback\*(C'\fR option is provided, it will be called iteratively until the entire response body is received. The first argument will be a string containing a chunk of the response body, the second argument will be the in-progress response hash reference, as described below. (This allows customizing the action of the callback based on the \f(CW\*(C`status\*(C'\fR or \f(CW\*(C`headers\*(C'\fR received prior to the content body.) .PP Content data in the request/response is handled as \*(L"raw bytes\*(R". Any encoding/decoding (with associated headers) are the responsibility of the caller. .PP The \f(CW\*(C`request\*(C'\fR method returns a hashref containing the response. The hashref will have the following keys: .IP "\(bu" 4 \&\f(CW\*(C`success\*(C'\fR — Boolean indicating whether the operation returned a 2XX status code .IP "\(bu" 4 \&\f(CW\*(C`url\*(C'\fR — \s-1URL\s0 that provided the response. This is the \s-1URL\s0 of the request unless there were redirections, in which case it is the last \s-1URL\s0 queried in a redirection chain .IP "\(bu" 4 \&\f(CW\*(C`status\*(C'\fR — The \s-1HTTP\s0 status code of the response .IP "\(bu" 4 \&\f(CW\*(C`reason\*(C'\fR — The response phrase returned by the server .IP "\(bu" 4 \&\f(CW\*(C`content\*(C'\fR — The body of the response. If the response does not have any content or if a data callback is provided to consume the response body, this will be the empty string .IP "\(bu" 4 \&\f(CW\*(C`headers\*(C'\fR — A hashref of header fields. All header field names will be normalized to be lower case. If a header is repeated, the value will be an arrayref; it will otherwise be a scalar string containing the value .IP "\(bu" 4 \&\f(CW\*(C`protocol\*(C'\fR \- If this field exists, it is the protocol of the response such as \s-1HTTP/1.0\s0 or \s-1HTTP/1.1\s0 .IP "\(bu" 4 \&\f(CW\*(C`redirects\*(C'\fR If this field exists, it is an arrayref of response hash references from redirects in the same order that redirections occurred. If it does not exist, then no redirections occurred. .PP On an error during the execution of the request, the \f(CW\*(C`status\*(C'\fR field will contain 599, and the \f(CW\*(C`content\*(C'\fR field will contain the text of the error. .SS "www_form_urlencode" .IX Subsection "www_form_urlencode" .Vb 2 \& $params = $http\->www_form_urlencode( $data ); \& $response = $http\->get("http://example.com/query?$params"); .Ve .PP This method converts the key/value pairs from a data hash or array reference into a \f(CW\*(C`x\-www\-form\-urlencoded\*(C'\fR string. The keys and values from the data reference will be \s-1UTF\-8\s0 encoded and escaped per \s-1RFC 3986.\s0 If a value is an array reference, the key will be repeated with each of the values of the array reference. If data is provided as a hash reference, the key/value pairs in the resulting string will be sorted by key and value for consistent ordering. .SS "can_ssl" .IX Subsection "can_ssl" .Vb 3 \& $ok = HTTP::Tiny\->can_ssl; \& ($ok, $why) = HTTP::Tiny\->can_ssl; \& ($ok, $why) = $http\->can_ssl; .Ve .PP Indicates if \s-1SSL\s0 support is available. When called as a class object, it checks for the correct version of Net::SSLeay and IO::Socket::SSL. When called as an object methods, if \f(CW\*(C`SSL_verify\*(C'\fR is true or if \f(CW\*(C`SSL_verify_mode\*(C'\fR is set in \f(CW\*(C`SSL_options\*(C'\fR, it checks that a \s-1CA\s0 file is available. .PP In scalar context, returns a boolean indicating if \s-1SSL\s0 is available. In list context, returns the boolean and a (possibly multi-line) string of errors indicating why \s-1SSL\s0 isn't available. .SS "connected" .IX Subsection "connected" .Vb 2 \& $host = $http\->connected; \& ($host, $port) = $http\->connected; .Ve .PP Indicates if a connection to a peer is being kept alive, per the \f(CW\*(C`keep_alive\*(C'\fR option. .PP In scalar context, returns the peer host and port, joined with a colon, or \&\f(CW\*(C`undef\*(C'\fR (if no peer is connected). In list context, returns the peer host and port or an empty list (if no peer is connected). .PP \&\fBNote\fR: This method cannot reliably be used to discover whether the remote host has closed its end of the socket. .SH "TLS/SSL SUPPORT" .IX Header "TLS/SSL SUPPORT" Direct \f(CW\*(C`https\*(C'\fR connections are supported only if IO::Socket::SSL 1.56 or greater and Net::SSLeay 1.49 or greater are installed. An error will occur if new enough versions of these modules are not installed or if the \s-1TLS\s0 encryption fails. You can also use \f(CW\*(C`HTTP::Tiny::can_ssl()\*(C'\fR utility function that returns boolean to see if the required modules are installed. .PP An \f(CW\*(C`https\*(C'\fR connection may be made via an \f(CW\*(C`http\*(C'\fR proxy that supports the \s-1CONNECT\s0 command (i.e. \s-1RFC 2817\s0). You may not proxy \f(CW\*(C`https\*(C'\fR via a proxy that itself requires \f(CW\*(C`https\*(C'\fR to communicate. .PP \&\s-1TLS/SSL\s0 provides two distinct capabilities: .IP "\(bu" 4 Encrypted communication channel .IP "\(bu" 4 Verification of server identity .PP \&\fBBy default, HTTP::Tiny verifies server identity\fR. .PP This was changed in version 0.083 due to security concerns. The previous default behavior can be enabled by setting \f(CW$ENV{PERL_HTTP_TINY_SSL_INSECURE_BY_DEFAULT}\fR to 1. .PP Verification is done by checking that that the \s-1TLS/SSL\s0 connection has a valid certificate corresponding to the host name of the connection and that the certificate has been verified by a \s-1CA.\s0 Assuming you trust the \s-1CA,\s0 this will protect against machine-in-the-middle attacks . .PP Certificate verification requires a file containing trusted \s-1CA\s0 certificates. .PP If the environment variable \f(CW\*(C`SSL_CERT_FILE\*(C'\fR is present, HTTP::Tiny will try to find a \s-1CA\s0 certificate file in that location. .PP If the Mozilla::CA module is installed, HTTP::Tiny will use the \s-1CA\s0 file included with it as a source of trusted \s-1CA\s0's. .PP If that module is not available, then HTTP::Tiny will search several system-specific default locations for a \s-1CA\s0 certificate file: .IP "\(bu" 4 /etc/ssl/certs/ca\-certificates.crt .IP "\(bu" 4 /etc/pki/tls/certs/ca\-bundle.crt .IP "\(bu" 4 /etc/ssl/ca\-bundle.pem .IP "\(bu" 4 /etc/openssl/certs/ca\-certificates.crt .IP "\(bu" 4 /etc/ssl/cert.pem .IP "\(bu" 4 /usr/local/share/certs/ca\-root\-nss.crt .IP "\(bu" 4 /etc/pki/tls/cacert.pem .IP "\(bu" 4 /etc/certs/ca\-certificates.crt .PP An error will be occur if \f(CW\*(C`verify_SSL\*(C'\fR is true and no \s-1CA\s0 certificate file is available. .PP If you desire complete control over \s-1TLS/SSL\s0 connections, the \f(CW\*(C`SSL_options\*(C'\fR attribute lets you provide a hash reference that will be passed through to \&\f(CW\*(C`IO::Socket::SSL::start_SSL()\*(C'\fR, overriding any options set by HTTP::Tiny. For example, to provide your own trusted \s-1CA\s0 file: .PP .Vb 3 \& SSL_options => { \& SSL_ca_file => $file_path, \& } .Ve .PP The \f(CW\*(C`SSL_options\*(C'\fR attribute could also be used for such things as providing a client certificate for authentication to a server or controlling the choice of cipher used for the \s-1TLS/SSL\s0 connection. See IO::Socket::SSL documentation for details. .SH "PROXY SUPPORT" .IX Header "PROXY SUPPORT" HTTP::Tiny can proxy both \f(CW\*(C`http\*(C'\fR and \f(CW\*(C`https\*(C'\fR requests. Only Basic proxy authorization is supported and it must be provided as part of the proxy \s-1URL:\s0 \&\f(CW\*(C`http://user:pass@proxy.example.com/\*(C'\fR. .PP HTTP::Tiny supports the following proxy environment variables: .IP "\(bu" 4 http_proxy or \s-1HTTP_PROXY\s0 .IP "\(bu" 4 https_proxy or \s-1HTTPS_PROXY\s0 .IP "\(bu" 4 all_proxy or \s-1ALL_PROXY\s0 .PP If the \f(CW\*(C`REQUEST_METHOD\*(C'\fR environment variable is set, then this might be a \s-1CGI\s0 process and \f(CW\*(C`HTTP_PROXY\*(C'\fR would be set from the \f(CW\*(C`Proxy:\*(C'\fR header, which is a security risk. If \f(CW\*(C`REQUEST_METHOD\*(C'\fR is set, \f(CW\*(C`HTTP_PROXY\*(C'\fR (the upper case variant only) is ignored, but \f(CW\*(C`CGI_HTTP_PROXY\*(C'\fR is considered instead. .PP Tunnelling \f(CW\*(C`https\*(C'\fR over an \f(CW\*(C`http\*(C'\fR proxy using the \s-1CONNECT\s0 method is supported. If your proxy uses \f(CW\*(C`https\*(C'\fR itself, you can not tunnel \f(CW\*(C`https\*(C'\fR over it. .PP Be warned that proxying an \f(CW\*(C`https\*(C'\fR connection opens you to the risk of a man-in-the-middle attack by the proxy server. .PP The \f(CW\*(C`no_proxy\*(C'\fR environment variable is supported in the format of a comma-separated list of domain extensions proxy should not be used for. .PP Proxy arguments passed to \f(CW\*(C`new\*(C'\fR will override their corresponding environment variables. .SH "LIMITATIONS" .IX Header "LIMITATIONS" HTTP::Tiny is \fIconditionally compliant\fR with the \&\s-1HTTP/1.1\s0 specifications : .IP "\(bu" 4 \&\*(L"Message Syntax and Routing\*(R" [\s-1RFC7230\s0] .IP "\(bu" 4 \&\*(L"Semantics and Content\*(R" [\s-1RFC7231\s0] .IP "\(bu" 4 \&\*(L"Conditional Requests\*(R" [\s-1RFC7232\s0] .IP "\(bu" 4 \&\*(L"Range Requests\*(R" [\s-1RFC7233\s0] .IP "\(bu" 4 \&\*(L"Caching\*(R" [\s-1RFC7234\s0] .IP "\(bu" 4 \&\*(L"Authentication\*(R" [\s-1RFC7235\s0] .PP It attempts to meet all \*(L"\s-1MUST\*(R"\s0 requirements of the specification, but does not implement all \*(L"\s-1SHOULD\*(R"\s0 requirements. (Note: it was developed against the earlier \s-1RFC 2616\s0 specification and may not yet meet the revised \s-1RFC 7230\-7235\s0 spec.) Additionally, HTTP::Tiny supports the \f(CW\*(C`PATCH\*(C'\fR method of \s-1RFC 5789.\s0 .PP Some particular limitations of note include: .IP "\(bu" 4 HTTP::Tiny focuses on correct transport. Users are responsible for ensuring that user-defined headers and content are compliant with the \s-1HTTP/1.1\s0 specification. .IP "\(bu" 4 Users must ensure that URLs are properly escaped for unsafe characters and that international domain names are properly encoded to \s-1ASCII.\s0 See URI::Escape, URI::_punycode and Net::IDN::Encode. .IP "\(bu" 4 Redirection is very strict against the specification. Redirection is only automatic for response codes 301, 302, 307 and 308 if the request method is \&'\s-1GET\s0' or '\s-1HEAD\s0'. Response code 303 is always converted into a '\s-1GET\s0' redirection, as mandated by the specification. There is no automatic support for status 305 (\*(L"Use proxy\*(R") redirections. .IP "\(bu" 4 There is no provision for delaying a request body using an \f(CW\*(C`Expect\*(C'\fR header. Unexpected \f(CW\*(C`1XX\*(C'\fR responses are silently ignored as per the specification. .IP "\(bu" 4 Only 'chunked' \f(CW\*(C`Transfer\-Encoding\*(C'\fR is supported. .IP "\(bu" 4 There is no support for a Request-URI of '*' for the '\s-1OPTIONS\s0' request. .IP "\(bu" 4 Headers mentioned in the RFCs and some other, well-known headers are generated with their canonical case. Other headers are sent in the case provided by the user. Except for control headers (which are sent first), headers are sent in arbitrary order. .PP Despite the limitations listed above, HTTP::Tiny is considered feature-complete. New feature requests should be directed to HTTP::Tiny::UA. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 HTTP::Tiny::UA \- Higher level \s-1UA\s0 features for HTTP::Tiny .IP "\(bu" 4 HTTP::Thin \- HTTP::Tiny wrapper with HTTP::Request/HTTP::Response compatibility .IP "\(bu" 4 HTTP::Tiny::Mech \- Wrap WWW::Mechanize instance in HTTP::Tiny compatible interface .IP "\(bu" 4 IO::Socket::IP \- Required for IPv6 support .IP "\(bu" 4 IO::Socket::SSL \- Required for \s-1SSL\s0 support .IP "\(bu" 4 LWP::UserAgent \- If HTTP::Tiny isn't enough for you, this is the \*(L"standard\*(R" way to do things .IP "\(bu" 4 Mozilla::CA \- Required if you want to validate \s-1SSL\s0 certificates .IP "\(bu" 4 Net::SSLeay \- Required for \s-1SSL\s0 support .SH "SUPPORT" .IX Header "SUPPORT" .SS "Bugs / Feature Requests" .IX Subsection "Bugs / Feature Requests" Please report any bugs or feature requests through the issue tracker at . You will be notified automatically of any progress on your issue. .SS "Source Code" .IX Subsection "Source Code" This is open source software. The code repository is available for public review and contribution under the terms of the license. .PP .PP .Vb 1 \& git clone https://github.com/Perl\-Toolchain\-Gang/HTTP\-Tiny.git .Ve .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 Christian Hansen .IP "\(bu" 4 David Golden .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Alan Gardner .IP "\(bu" 4 Alessandro Ghedini .IP "\(bu" 4 A. Sinan Unur .IP "\(bu" 4 Brad Gilbert .IP "\(bu" 4 brian m. carlson .IP "\(bu" 4 Chris Nehren .IP "\(bu" 4 Chris Weyl .IP "\(bu" 4 Claes Jakobsson .IP "\(bu" 4 Clinton Gormley .IP "\(bu" 4 Craig A. Berry .IP "\(bu" 4 Craig Berry .IP "\(bu" 4 David Golden .IP "\(bu" 4 David Mitchell .IP "\(bu" 4 Dean Pearce .IP "\(bu" 4 Edward Zborowski .IP "\(bu" 4 Felipe Gasper .IP "\(bu" 4 Graham Knop .IP "\(bu" 4 Greg Kennedy .IP "\(bu" 4 James E Keenan .IP "\(bu" 4 James Raspass .IP "\(bu" 4 Jeremy Mates .IP "\(bu" 4 Jess Robinson .IP "\(bu" 4 Karen Etheridge .IP "\(bu" 4 Lukas Eklund .IP "\(bu" 4 Martin J. Evans .IP "\(bu" 4 Martin-Louis Bright .IP "\(bu" 4 Matthew Horsfall .IP "\(bu" 4 Michael R. Davis .IP "\(bu" 4 Mike Doherty .IP "\(bu" 4 Nicolas Rochelemagne .IP "\(bu" 4 Olaf Alders .IP "\(bu" 4 Olivier Mengué .IP "\(bu" 4 Petr Písař .IP "\(bu" 4 sanjay-cpu .IP "\(bu" 4 Serguei Trouchelle .IP "\(bu" 4 Shoichi Kaji .IP "\(bu" 4 SkyMarshal .IP "\(bu" 4 Sören Kornetzki .IP "\(bu" 4 Steve Grazzini .IP "\(bu" 4 Stig Palmquist .IP "\(bu" 4 Syohei \s-1YOSHIDA\s0 .IP "\(bu" 4 Tatsuhiko Miyagawa .IP "\(bu" 4 Tom Hukins .IP "\(bu" 4 Tony Cook .IP "\(bu" 4 Xavier Guimard .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2023 by Christian Hansen. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. PK@O\O..Types::Serialiser.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Serialiser 3" .TH Serialiser 3 "2020-12-01" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Types::Serialiser \- simple data types for common serialisation formats .SH "SYNOPSIS" .IX Header "SYNOPSIS" .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides some extra datatypes that are used by common serialisation formats such as \s-1JSON\s0 or \s-1CBOR.\s0 The idea is to have a repository of simple/small constants and containers that can be shared by different implementations so they become interoperable between each other. .SH "SIMPLE SCALAR CONSTANTS" .IX Header "SIMPLE SCALAR CONSTANTS" Simple scalar constants are values that are overloaded to act like simple Perl values, but have (class) type to differentiate them from normal Perl scalars. This is necessary because these have different representations in the serialisation formats. .PP In the following, functions with zero or one arguments have a prototype of \&\f(CW\*(C`()\*(C'\fR and \f(CW\*(C`($)\*(C'\fR, respectively, so act as constants and unary operators. .SS "\s-1BOOLEANS\s0 (Types::Serialiser::Boolean class)" .IX Subsection "BOOLEANS (Types::Serialiser::Boolean class)" This type has only two instances, true and false. A natural representation for these in Perl is \f(CW1\fR and \f(CW0\fR, but serialisation formats need to be able to differentiate between them and mere numbers. .ie n .IP "$Types::Serialiser::true, Types::Serialiser::true" 4 .el .IP "\f(CW$Types::Serialiser::true\fR, Types::Serialiser::true" 4 .IX Item "$Types::Serialiser::true, Types::Serialiser::true" This value represents the \*(L"true\*(R" value. In most contexts is acts like the number \f(CW1\fR. It is up to you whether you use the variable form (\f(CW$Types::Serialiser::true\fR) or the constant form (\f(CW\*(C`Types::Serialiser::true\*(C'\fR). .Sp The constant is represented as a reference to a scalar containing \f(CW1\fR \- implementations are allowed to directly test for this. .ie n .IP "$Types::Serialiser::false, Types::Serialiser::false" 4 .el .IP "\f(CW$Types::Serialiser::false\fR, Types::Serialiser::false" 4 .IX Item "$Types::Serialiser::false, Types::Serialiser::false" This value represents the \*(L"false\*(R" value. In most contexts is acts like the number \f(CW0\fR. It is up to you whether you use the variable form (\f(CW$Types::Serialiser::false\fR) or the constant form (\f(CW\*(C`Types::Serialiser::false\*(C'\fR). .Sp The constant is represented as a reference to a scalar containing \f(CW0\fR \- implementations are allowed to directly test for this. .ie n .IP "Types::Serialiser::as_bool $value" 4 .el .IP "Types::Serialiser::as_bool \f(CW$value\fR" 4 .IX Item "Types::Serialiser::as_bool $value" Converts a Perl scalar into a boolean, which is useful syntactic sugar. Strictly equivalent to: .Sp .Vb 1 \& $value ? $Types::Serialiser::true : $Types::Serialiser::false .Ve .ie n .IP "$is_bool = Types::Serialiser::is_bool $value" 4 .el .IP "\f(CW$is_bool\fR = Types::Serialiser::is_bool \f(CW$value\fR" 4 .IX Item "$is_bool = Types::Serialiser::is_bool $value" Returns true iff the \f(CW$value\fR is either \f(CW$Types::Serialiser::true\fR or \&\f(CW$Types::Serialiser::false\fR. .Sp For example, you could differentiate between a perl true value and a \&\f(CW\*(C`Types::Serialiser::true\*(C'\fR by using this: .Sp .Vb 1 \& $value && Types::Serialiser::is_bool $value .Ve .ie n .IP "$is_true = Types::Serialiser::is_true $value" 4 .el .IP "\f(CW$is_true\fR = Types::Serialiser::is_true \f(CW$value\fR" 4 .IX Item "$is_true = Types::Serialiser::is_true $value" Returns true iff \f(CW$value\fR is \f(CW$Types::Serialiser::true\fR. .ie n .IP "$is_false = Types::Serialiser::is_false $value" 4 .el .IP "\f(CW$is_false\fR = Types::Serialiser::is_false \f(CW$value\fR" 4 .IX Item "$is_false = Types::Serialiser::is_false $value" Returns false iff \f(CW$value\fR is \f(CW$Types::Serialiser::false\fR. .SS "\s-1ERROR\s0 (Types::Serialiser::Error class)" .IX Subsection "ERROR (Types::Serialiser::Error class)" This class has only a single instance, \f(CW\*(C`error\*(C'\fR. It is used to signal an encoding or decoding error. In \s-1CBOR\s0 for example, and object that couldn't be encoded will be represented by a \s-1CBOR\s0 undefined value, which is represented by the error value in Perl. .ie n .IP "$Types::Serialiser::error, Types::Serialiser::error" 4 .el .IP "\f(CW$Types::Serialiser::error\fR, Types::Serialiser::error" 4 .IX Item "$Types::Serialiser::error, Types::Serialiser::error" This value represents the \*(L"error\*(R" value. Accessing values of this type will throw an exception. .Sp The constant is represented as a reference to a scalar containing \f(CW\*(C`undef\*(C'\fR \&\- implementations are allowed to directly test for this. .ie n .IP "$is_error = Types::Serialiser::is_error $value" 4 .el .IP "\f(CW$is_error\fR = Types::Serialiser::is_error \f(CW$value\fR" 4 .IX Item "$is_error = Types::Serialiser::is_error $value" Returns false iff \f(CW$value\fR is \f(CW$Types::Serialiser::error\fR. .SH "NOTES FOR XS USERS" .IX Header "NOTES FOR XS USERS" The recommended way to detect whether a scalar is one of these objects is to check whether the stash is the \f(CW\*(C`Types::Serialiser::Boolean\*(C'\fR or \&\f(CW\*(C`Types::Serialiser::Error\*(C'\fR stash, and then follow the scalar reference to see if it's \f(CW1\fR (true), \f(CW0\fR (false) or \f(CW\*(C`undef\*(C'\fR (error). .PP While it is possible to use an isa test, directly comparing stash pointers is faster and guaranteed to work. .PP For historical reasons, the \f(CW\*(C`Types::Serialiser::Boolean\*(C'\fR stash is just an alias for \f(CW\*(C`JSON::PP::Boolean\*(C'\fR. When printed, the classname with usually be \f(CW\*(C`JSON::PP::Boolean\*(C'\fR, but isa tests and stash pointer comparison will normally work correctly (i.e. Types::Serialiser::true \s-1ISA\s0 JSON::PP::Boolean, but also \s-1ISA\s0 Types::Serialiser::Boolean). .SH "A GENERIC OBJECT SERIALIATION PROTOCOL" .IX Header "A GENERIC OBJECT SERIALIATION PROTOCOL" This section explains the object serialisation protocol used by \&\s-1CBOR::XS\s0. It is meant to be generic enough to support any kind of generic object serialiser. .PP This protocol is called \*(L"the Types::Serialiser object serialisation protocol\*(R". .SS "\s-1ENCODING\s0" .IX Subsection "ENCODING" When the encoder encounters an object that it cannot otherwise encode (for example, \s-1CBOR::XS\s0 can encode a few special types itself, and will first attempt to use the special \f(CW\*(C`TO_CBOR\*(C'\fR serialisation protocol), it will look up the \f(CW\*(C`FREEZE\*(C'\fR method on the object. .PP Note that the \f(CW\*(C`FREEZE\*(C'\fR method will normally be called \fIduring\fR encoding, and \fI\s-1MUST NOT\s0\fR change the data structure that is being encoded in any way, or it might cause memory corruption or worse. .PP If it exists, it will call it with two arguments: the object to serialise, and a constant string that indicates the name of the data model. For example \s-1CBOR::XS\s0 uses \f(CW\*(C`CBOR\*(C'\fR, and the \s-1JSON\s0 and \s-1JSON::XS\s0 modules (or any other \s-1JSON\s0 serialiser), would use \f(CW\*(C`JSON\*(C'\fR as second argument. .PP The \f(CW\*(C`FREEZE\*(C'\fR method can then return zero or more values to identify the object instance. The serialiser is then supposed to encode the class name and all of these return values (which must be encodable in the format) using the relevant form for Perl objects. In \s-1CBOR\s0 for example, there is a registered tag number for encoded perl objects. .PP The values that \f(CW\*(C`FREEZE\*(C'\fR returns must be serialisable with the serialiser that calls it. Therefore, it is recommended to use simple types such as strings and numbers, and maybe array references and hashes (basically, the \&\s-1JSON\s0 data model). You can always use a more complex format for a specific data model by checking the second argument, the data model. .PP The \*(L"data model\*(R" is not the same as the \*(L"data format\*(R" \- the data model indicates what types and kinds of return values can be returned from \&\f(CW\*(C`FREEZE\*(C'\fR. For example, in \f(CW\*(C`CBOR\*(C'\fR it is permissible to return tagged \s-1CBOR\s0 values, while \s-1JSON\s0 does not support these at all, so \f(CW\*(C`JSON\*(C'\fR would be a valid (but too limited) data model name for \f(CW\*(C`CBOR::XS\*(C'\fR. similarly, a serialising format that supports more or less the same data model as \s-1JSON\s0 could use \f(CW\*(C`JSON\*(C'\fR as data model without losing anything. .SS "\s-1DECODING\s0" .IX Subsection "DECODING" When the decoder then encounters such an encoded perl object, it should look up the \f(CW\*(C`THAW\*(C'\fR method on the stored classname, and invoke it with the classname, the constant string to identify the data model/data format, and all the return values returned by \f(CW\*(C`FREEZE\*(C'\fR. .SS "\s-1EXAMPLES\s0" .IX Subsection "EXAMPLES" See the \f(CW\*(C`OBJECT SERIALISATION\*(C'\fR section in the \s-1CBOR::XS\s0 manpage for more details, an example implementation, and code examples. .PP Here is an example \f(CW\*(C`FREEZE\*(C'\fR/\f(CW\*(C`THAW\*(C'\fR method pair: .PP .Vb 2 \& sub My::Object::FREEZE { \& my ($self, $model) = @_; \& \& ($self\->{type}, $self\->{id}, $self\->{variant}) \& } \& \& sub My::Object::THAW { \& my ($class, $model, $type, $id, $variant) = @_; \& \& $class\->new (type => $type, id => $id, variant => $variant) \& } .Ve .SH "BUGS" .IX Header "BUGS" The use of overload makes this module much heavier than it should be (on my system, this module: 4kB \s-1RSS,\s0 overload: 260kB \s-1RSS\s0). .SH "SEE ALSO" .IX Header "SEE ALSO" Currently, \s-1JSON::XS\s0 and \s-1CBOR::XS\s0 use these types. .SH "AUTHOR" .IX Header "AUTHOR" .Vb 2 \& Marc Lehmann \& http://home.schmorp.de/ .Ve PK@O\D% % JSON::XS::Boolean.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "XS::Boolean 3" .TH XS::Boolean 3 "2013-10-29" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" JSON::XS::Boolean \- dummy module providing JSON::XS::Boolean .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& # do not "use" yourself .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module exists only to provide overload resolution for Storable and similar modules. It's only needed for compatibility with data serialised (by other modules such as Storable) that was decoded by \s-1JSON::XS\s0 versions before 3.0. .PP Since 3.0, JSON::PP::Boolean has replaced it. Support for JSON::XS::Boolean will be removed in a future release. .SH "AUTHOR" .IX Header "AUTHOR" .Vb 2 \& Marc Lehmann \& http://home.schmorp.de/ .Ve PK@O\common::sense.3pmnu6$PK@O\Jt t CPAN::Tarzip.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::Tarzip 3" .TH CPAN::Tarzip 3 "2020-05-19" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::Tarzip \- internal handling of tar archives for CPAN.pm .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK@O\ CPAN::Plugin.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::Plugin 3" .TH CPAN::Plugin 3 "2020-05-19" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::Plugin \- Base class for CPAN shell extensions .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& package CPAN::Plugin::Flurb; \& use parent \*(AqCPAN::Plugin\*(Aq; \& \& sub post_test { \& my ($self, $distribution_object) = @_; \& $self = $self\->new (distribution_object => $distribution_object); \& ...; \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" .SS "Alpha Status" .IX Subsection "Alpha Status" The plugin system in the \s-1CPAN\s0 shell was introduced in version 2.07 and is still considered experimental. .SS "How Plugins work?" .IX Subsection "How Plugins work?" See \*(L"Plugin support\*(R" in \s-1CPAN\s0. .SH "METHODS" .IX Header "METHODS" .SS "plugin_requires" .IX Subsection "plugin_requires" returns list of packages given plugin requires for functionality. This list is evaluated using \f(CW\*(C`CPAN\->use_inst\*(C'\fR method. .SS "distribution_object" .IX Subsection "distribution_object" Get current distribution object. .SS "distribution" .IX Subsection "distribution" .SS "distribution_info" .IX Subsection "distribution_info" .SS "build_dir" .IX Subsection "build_dir" Simple delegatees for misc parameters derived from distribution .SS "is_xs" .IX Subsection "is_xs" Predicate to detect whether package contains \s-1XS.\s0 .SH "AUTHOR" .IX Header "AUTHOR" Branislav Zahradnik PK@O\a!CPAN::Distroprefs.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::Distroprefs 3" .TH CPAN::Distroprefs 3 "2020-03-01" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::Distroprefs \-\- read and match distroprefs .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use CPAN::Distroprefs; \& \& my %info = (... distribution/environment info ...); \& \& my $finder = CPAN::Distroprefs\->find($prefs_dir, \e%ext_map); \& \& while (my $result = $finder\->next) { \& \& die $result\->as_string if $result\->is_fatal; \& \& warn($result\->as_string), next if $result\->is_warning; \& \& for my $pref (@{ $result\->prefs }) { \& if ($pref\->matches(\e%info)) { \& return $pref; \& } \& } \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module encapsulates reading Distroprefs and matching them against \s-1CPAN\s0 distributions. .SH "INTERFACE" .IX Header "INTERFACE" .Vb 1 \& my $finder = CPAN::Distroprefs\->find($dir, \e%ext_map); \& \& while (my $result = $finder\->next) { ... } .Ve .PP Build an iterator which finds distroprefs files in the tree below the given directory. Within the tree directories matching \f(CW\*(C`m/^[._]/\*(C'\fR are pruned. .PP \&\f(CW%ext_map\fR is a hashref whose keys are file extensions and whose values are modules used to load matching files: .PP .Vb 5 \& { \& \*(Aqyml\*(Aq => \*(AqYAML::Syck\*(Aq, \& \*(Aqdd\*(Aq => \*(AqData::Dumper\*(Aq, \& ... \& } .Ve .PP Each time \f(CW\*(C`$finder\->next\*(C'\fR is called, the iterator returns one of two possible values: .IP "\(bu" 4 a CPAN::Distroprefs::Result object .IP "\(bu" 4 \&\f(CW\*(C`undef\*(C'\fR, indicating that no prefs files remain to be found .SH "RESULTS" .IX Header "RESULTS" \&\f(CW\*(C`find()\*(C'\fR returns CPAN::Distroprefs::Result objects to indicate success or failure when reading a prefs file. .SS "Common" .IX Subsection "Common" All results share some common attributes: .PP \fItype\fR .IX Subsection "type" .PP \&\f(CW\*(C`success\*(C'\fR, \f(CW\*(C`warning\*(C'\fR, or \f(CW\*(C`fatal\*(C'\fR .PP \fIfile\fR .IX Subsection "file" .PP the file from which these prefs were read, or to which this error refers (relative filename) .PP \fIext\fR .IX Subsection "ext" .PP the file's extension, which determines how to load it .PP \fIdir\fR .IX Subsection "dir" .PP the directory the file was read from .PP \fIabs\fR .IX Subsection "abs" .PP the absolute path to the file .SS "Errors" .IX Subsection "Errors" Error results (warning and fatal) contain: .PP \fImsg\fR .IX Subsection "msg" .PP the error message (usually either \f(CW$!\fR or a \s-1YAML\s0 error) .SS "Successes" .IX Subsection "Successes" Success results contain: .PP \fIprefs\fR .IX Subsection "prefs" .PP an arrayref of CPAN::Distroprefs::Pref objects .SH "PREFS" .IX Header "PREFS" CPAN::Distroprefs::Pref objects represent individual distroprefs documents. They are constructed automatically as part of \f(CW\*(C`success\*(C'\fR results from \f(CW\*(C`find()\*(C'\fR. .PP \fIdata\fR .IX Subsection "data" .PP the pref information as a hashref, suitable for e.g. passing to Kwalify .PP \fImatch_attributes\fR .IX Subsection "match_attributes" .PP returns a list of the valid match attributes (see the Distroprefs section in \s-1CPAN\s0) .PP currently: \f(CW\*(C`env perl perlconfig distribution module\*(C'\fR .PP \fIhas_any_match\fR .IX Subsection "has_any_match" .PP true if this pref has a 'match' attribute at all .PP \fIhas_valid_subkeys\fR .IX Subsection "has_valid_subkeys" .PP true if this pref has a 'match' attribute and at least one valid match attribute .PP \fImatches\fR .IX Subsection "matches" .PP .Vb 1 \& if ($pref\->matches(\e%arg)) { ... } .Ve .PP true if this pref matches the passed-in hashref, which must have a value for each of the \f(CW\*(C`match_attributes\*(C'\fR (above) .SH "LICENSE" .IX Header "LICENSE" This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. PK@O\&DCPAN::Plugin::Specfile.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "CPAN::Plugin::Specfile 3" .TH CPAN::Plugin::Specfile 3 "2020-05-19" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" CPAN::Plugin::Specfile \- Proof of concept implementation of a trivial CPAN::Plugin .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # once in the cpan shell \& o conf plugin_list push CPAN::Plugin::Specfile \& \& # make permanent \& o conf commit \& \& # any time in the cpan shell to write a spec file \& test Acme::Meta \& \& # disable \& # if it is the last in plugin_list: \& o conf plugin_list pop \& # otherwise, determine the index to splice: \& o conf plugin_list \& # and then use splice, e.g. to splice position 3: \& o conf plugin_list splice 3 1 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Implemented as a post-test hook, this plugin writes a specfile after every successful test run. The content is also written to the terminal. .PP As a side effect, the timestamps of the written specfiles reflect the linear order of all dependencies. .PP \&\fB\s-1WARNING:\s0\fR This code is just a small demo how to use the plugin system of the \s-1CPAN\s0 shell, not a full fledged spec file writer. Do not expect new features in this plugin. .SS "\s-1OPTIONS\s0" .IX Subsection "OPTIONS" The target directory to store the spec files in can be set using \f(CW\*(C`dir\*(C'\fR as in .PP .Vb 1 \& o conf plugin_list push CPAN::Plugin::Specfile=dir,/tmp/specfiles\-000042 .Ve .PP The default directory for this is the \&\f(CW\*(C`plugins/CPAN::Plugin::Specfile\*(C'\fR directory in the \fIcpan_home\fR directory. .SH "AUTHOR" .IX Header "AUTHOR" Andreas Koenig , Branislav Zahradnik PK@O\ ,  lib::core::only.3pmnu6$.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "lib::core::only 3" .TH lib::core::only 3 "2017-11-08" "perl v5.26.3" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" lib::core::only \- Remove all non\-core paths from @INC to avoid site/vendor dirs .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use lib::core::only; # now @INC contains only the two core directories .Ve .PP To get only the core directories plus the ones for the local::lib in scope: .PP .Vb 1 \& $ perl \-mlocal::lib \-Mlib::core::only \-Mlocal::lib=~/perl5 myscript.pl .Ve .PP To attempt to do a self-contained build (but note this will not reliably propagate into subprocesses, see the \s-1CAVEATS\s0 below): .PP .Vb 1 \& $ PERL5OPT=\*(Aq\-mlocal::lib \-Mlib::core::only \-Mlocal::lib=~/perl5\*(Aq cpan .Ve .PP Please note that it is necessary to use \f(CW\*(C`local::lib\*(C'\fR twice for this to work. First so that \f(CW\*(C`lib::core::only\*(C'\fR doesn't prevent \f(CW\*(C`local::lib\*(C'\fR from loading (it's not currently in core) and then again after \f(CW\*(C`lib::core::only\*(C'\fR so that the local paths are not removed. .SH "DESCRIPTION" .IX Header "DESCRIPTION" lib::core::only is simply a shortcut to say \*(L"please reduce my \f(CW@INC\fR to only the core lib and archlib (architecture-specific lib) directories of this perl\*(R". .PP You might want to do this to ensure a local::lib contains only the code you need, or to test an App::FatPacker tree, or to avoid known bad vendor packages. .PP You might want to use this to try and install a self-contained tree of perl modules. Be warned that that probably won't work (see \*(L"\s-1CAVEATS\*(R"\s0). .PP This module was extracted from local::lib's \-\-self\-contained feature, and contains the only part that ever worked. I apologise to anybody who thought anything else did. .SH "CAVEATS" .IX Header "CAVEATS" This does \fBnot\fR propagate properly across perl invocations like local::lib's stuff does. It can't. It's only a module import, so it \fBonly affects the specific perl \s-1VM\s0 instance in which you load and \fBimport()\fB it\fR. .PP If you want to cascade it across invocations, you can set the \s-1PERL5OPT\s0 environment variable to '\-Mlib::core::only' and it'll sort of work. But be aware that taint mode ignores this, so some modules' build and test code probably will as well. .PP You also need to be aware that perl's command line options are not processed in order \- \-I options take effect before \-M options, so .PP .Vb 1 \& perl \-Mlib::core::only \-Ilib .Ve .PP is unlike to do what you want \- it's exactly equivalent to: .PP .Vb 1 \& perl \-Mlib::core::only .Ve .PP If you want to combine a core-only \f(CW@INC\fR with additional paths, you need to add the additional paths using \-M options and the lib module: .PP .Vb 1 \& perl \-Mlib::core::only \-Mlib=lib \& \& # or if you\*(Aqre trying to test compiled code: \& \& perl \-Mlib::core::only \-Mblib .Ve .PP For more information on the impossibility of sanely propagating this across module builds without help from the build program, see \- and for ways to achieve the old \-\-self\-contained feature's results, look at App::FatPacker's tree function, and at App::cpanminus's \-\-local\-lib\-contained feature. .SH "AUTHOR" .IX Header "AUTHOR" Matt S. Trout .SH "LICENSE" .IX Header "LICENSE" This library is free software under the same terms as perl itself. .SH "COPYRIGHT" .IX Header "COPYRIGHT" (c) 2010 the lib::core::only \*(L"\s-1AUTHOR\*(R"\s0 as specified above. PKO\ 0 shadow.3.gznu[PK@O\$m6m6 version.3pmnu6$PK@O\uTf f >CPAN::Queue.3pmnu6$PK@O\ 0HIO::Tty.3pmnu6$PK@O\IyGiLWP::Protocol::https.3pmnu6$PK@O\I*I*DyYAML::Syck.3pmnu6$PK@O\5ܚ11ˣCPAN::Meta::Requirements.3pmnu6$PK@O\ Y YPOD2::DE::local::lib.3pmnu6$PK@O\Hy /CPAN::Version.3pmnu6$PK@O\/LL2<Canary::Stability.3pmnu6$PK@O\W]# %%#LCPAN::Meta::Requirements::Range.3pmnu6$PK@O\stb b ;iCPAN::Debug.3pmnu6$PK@O\r4J||rlocal::lib.3pmnu6$PK@O\+ihA@Q@Q ,Try::Tiny.3pmnu6$PK@O\>DKvKv@version::Internals.3pmnu6$PK@O\?&&:CPAN::Admin.3pmnu6$PK@O\ m mCPAN::FirstTime.3pmnu6$PK@O\u{ 5Types::Serialiser::Error.3pmnu6$PK@O\*'E""@CPAN::Mirrors.3pmnu6$PK@O\lg cCPAN::Kwalify.3pmnu6$PK@O\އg! ! qCPAN::Nox.3pmnu6$PK@O\[//F}CPAN.3pmnu6$PK@O\W>JSON::Syck.3pmnu6$PK@O\qo[[ ^JSON::XS.3pmnu6$PK@O\%%~IO::Tty::Constant.3pmnu6$PK@O\j, CPAN::HandleConfig.3pmnu6$PK@O\LL Expect.3pmnu6$PK@O\z!! tIO::Pty.3pmnu6$PK@O\EX:22 .App::Cpan.3pmnu6$PK@O\< 20CPAN::API::HOWTO.3pmnu6$PK@O\+YҚXXt>POD2::PT_BR::local::lib.3pmnu6$PK@O\UeBJBJ YSwitch.3pmnu6$PK@O\E4nnHTTP::Tiny.3pmnu6$PK@O\O..P Types::Serialiser.3pmnu6$PK@O\D% %  JSON::XS::Boolean.3pmnu6$PK@O\ common::sense.3pmnu6$PK@O\Jt t ] CPAN::Tarzip.3pmnu6$PK@O\  CPAN::Plugin.3pmnu6$PK@O\a!8 CPAN::Distroprefs.3pmnu6$PK@O\&DE CPAN::Plugin::Specfile.3pmnu6$PK@O\ ,  C lib::core::only.3pmnu6$PK))