======================================================================== * README ======================================================================== Perl is Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 by Larry Wall and others. All rights reserved. ABOUT PERL ========== Perl is a general-purpose programming language originally developed for text manipulation and now used for a wide range of tasks including system administration, web development, network programming, GUI development, and more. The language is intended to be practical (easy to use, efficient, complete) rather than beautiful (tiny, elegant, minimal). Its major features are that it's easy to use, supports both procedural and object-oriented (OO) programming, has powerful built-in support for text processing, and has one of the world's most impressive collections of third-party modules. For an introduction to the language's features, see pod/perlintro.pod. For a discussion of the important changes in this release, see pod/perldelta.pod. There are also many Perl books available, covering a wide variety of topics, from various publishers. See pod/perlbook.pod for more information. INSTALLATION ============ If you're using a relatively modern operating system and want to install this version of Perl locally, run the following commands: ./Configure -des -Dprefix=$HOME/localperl make test make install This will configure and compile perl for your platform, run the regression tests, and install perl in a subdirectory "localperl" of your home directory. If you run into any trouble whatsoever or you need to install a customized version of Perl, you should read the detailed instructions in the "INSTALL" file that came with this distribution. Additionally, there are a number of "README" files with hints and tips about building and using Perl on a wide variety of platforms, some more common than others. Once you have Perl installed, a wealth of documentation is available to you through the 'perldoc' tool. To get started, run this command: perldoc perl IF YOU RUN INTO TROUBLE ======================= Perl is a large and complex system that's used for everything from knitting to rocket science. If you run into trouble, it's quite likely that someone else has already solved the problem you're facing. Once you've exhausted the documentation, please report bugs to us using the 'perlbug' tool. For more information about perlbug, either type 'perldoc perlbug' or just 'perlbug' on a line by itself. While it was current when we made it available, Perl is constantly evolving and there may be a more recent version that fixes bugs you've run into or adds new features that you might find useful. You can always find the latest version of perl on a CPAN (Comprehensive Perl Archive Network) site near you at http://www.cpan.org/src/ Just a personal note: I want you to know that I create nice things like this because it pleases the Author of my story. If this bothers you, then your notion of Authorship needs some revision. But you can use perl anyway. :-) The author. LICENSING ========= This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" which comes with this Kit. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details. You should have received a copy of the Artistic License with this Kit, in the file named "Artistic". If not, I'll be glad to provide one. You should also have received a copy of the GNU General Public License along with this program in the file named "Copying". If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA or visit their web page on the internet at http://www.gnu.org/copyleft/gpl.html. For those of you that choose to use the GNU General Public License, my interpretation of the GNU General Public License is that no Perl script falls under the terms of the GPL unless you explicitly put said script under the terms of the GPL yourself. Furthermore, any object code linked with perl does not automatically fall under the terms of the GPL, provided such object code only adds definitions of subroutines and variables, and does not otherwise impair the resulting interpreter from executing any standard Perl script. I consider linking in C subroutines in this manner to be the moral equivalent of defining subroutines in the Perl language itself. You may sell such an object file as proprietary provided that you provide or offer to provide the Perl source, as specified by the GNU General Public License. (This is merely an alternate way of specifying input to the program.) You may also sell a binary produced by the dumping of a running Perl script that belongs to you, provided that you provide or offer to provide the Perl source as specified by the GPL. (The fact that a Perl interpreter and your code are in the same binary file is, in this case, a form of mere aggregation.) This is my interpretation of the GPL. If you still have concerns or difficulties understanding my intent, feel free to contact me. Of course, the Artistic License spells all this out for your protection, so you may prefer to use that. ======================================================================== * README.symbian ======================================================================== If you read this file _as_is_, just ignore the funny characters you see. It is written in the POD format (see pod/perlpod.pod) which is specially designed to be readable as is. =head1 NAME perlsymbian - Perl version 5 on Symbian OS =head1 DESCRIPTION This document describes various features of the Symbian operating system that will affect how Perl version 5 (hereafter just Perl) is compiled and/or runs. B The DLL includes a C++ class called CPerlBase, which one can then (derive from and) use to embed Perl into applications, see F. The base port of Perl to Symbian only implements the basic POSIX-like functionality; it does not implement any further Symbian or Series 60, Series 80, or UIQ bindings for Perl. It is also possible to generate Symbian executables for "miniperl" and "perl", but since there is no standard command line interface for Symbian (nor full keyboards in the devices), these are useful mainly as demonstrations. =head2 Compiling Perl on Symbian (0) You need to have the appropriate Symbian SDK installed. These instructions have been tested under various Nokia Series 60 Symbian SDKs (1.2 to 2.6, 2.8 should also work, 1.2 compiles but does not work), Series 80 2.0, and Nokia 7710 (Series 90) SDK. You can get the SDKs from Forum Nokia (L). A very rough port ("it compiles") to UIQ 2.1 has also been made. A prerequisite for any of the SDKs is to install ActivePerl from ActiveState, L Having the SDK installed also means that you need to have either the Metrowerks CodeWarrior installed (2.8 and 3.0 were used in testing) or the Microsoft Visual C++ 6.0 installed (SP3 minimum, SP5 recommended). Note that for example the Series 60 2.0 VC SDK installation talks about ActivePerl build 518, which does no more (as of mid-2005) exist at the ActiveState website. The ActivePerl 5.8.4 build 810 was used successfully for compiling Perl on Symbian. The 5.6.x ActivePerls do not work. Other SDKs or compilers like Visual.NET, command-line-only Visual.NET, Borland, GnuPoc, or sdk2unix have not been tried. These instructions almost certainly won't work with older Symbian releases or other SDKs. Patches to get this port running in other releases, SDKs, compilers, platforms, or devices are naturally welcome. (1) Get a Perl source code distribution (for example the file perl-5.9.2.tar.gz is fine) from L and unpack it in your the C:/Symbian directory of your Windows system. (2) Change to the perl source directory. cd c:\Symbian\perl-5.x.x (3) Run the following script using the perl coming with the SDK perl symbian\config.pl You must use the cmd.exe, the Cygwin shell will not work. The PATH must include the SDK tools, including a Perl, which should be the case under cmd.exe. If you do not have that, see the end of symbian\sdk.pl for notes of how your environment should be set up for Symbian compiles. (4) Build the project, either by make all in cmd.exe or by using either the Metrowerks CodeWarrior or the Visual C++ 6.0, or the Visual Studio 8 (the Visual C++ 2005 Express Edition works fine). If you use the VC IDE, you will have to run F first using the cmd.exe, and then run 'make win.mf vc6.mf' to generate the VC6 makefiles and workspaces. "make vc6" will compile for the VC6, and "make cw" for the CodeWarrior. The following SDK and compiler configurations and Nokia phones were tested at some point in time (+ = compiled and PerlApp run, - = not), both for Perl 5.8.x and 5.9.x: SDK | VC | CW | --------+----+----+--- S60 1.2 | + | + | 3650 (*) S60 2.0 | + | + | 6600 S60 2.1 | - | + | 6670 S60 2.6 | + | + | 6630 S60 2.8 | + | + | (not tested in a device) S80 2.6 | - | + | 9300 S90 1.1 | + | - | 7710 UIQ 2.1 | - | + | (not tested in a device) (*) Compiles but does not work, unfortunately, a problem with Symbian. If you are using the 'make' directly, it is the GNU make from the SDKs, and it will invoke the right make commands for the Windows emulator build and the Arm target builds ('thumb' by default) as necessary. The build scripts assume the 'absolute style' SDK installs under C:, the 'subst style' will not work. If using the VC IDE, to build use for example the File->Open Workspace-> C:\Symbian\8.0a\S60_2nd_FP2\epoc32\build\symbian\perl\perl\wins\perl.dsw The emulator binaries will appear in the same directory. If using the VC IDE, you will a lot of warnings in the beginning of the build because a lot of headers mentioned by the source cannot be found, but this is not serious since those headers are not used. The Metrowerks will give a lot of warnings about unused variables and empty declarations, you can ignore those. When the Windows and Arm DLLs are built do not be scared by a very long messages whizzing by: it is the "export freeze" phase where the whole (rather large) API of Perl is listed. Once the build is completed you need to create the DLL SIS file by make perldll.sis which will create the file perlXYZ.sis (the XYZ being the Perl version) which you can then install into your Symbian device: an easy way to do this is to send them via Bluetooth or infrared and just open the messages. Since the total size of all Perl SIS files once installed is over 2 MB, it is recommended to do the installation into a memory card (drive E:) instead of the C: drive. The size of the perlXYZ.SIS is about 370 kB but once it is in the device it is about one 750 kB (according to the application manager). The perlXYZ.sis includes only the Perl DLL: to create an additional SIS file which includes some of the standard (pure) Perl libraries, issue the command make perllib.sis Some of the standard Perl libraries are included, but not all: see L or F for more details (250 kB -> 700 kB). Some of the standard Perl XS extensions (see L are also available: make perlext.sis which will create perlXYZext.sis (290 kB -> 770 kB). To compile the demonstration application PerlApp you need first to install the Perl headers under the SDK. To install the Perl headers and the class CPerlBase documentation so that you no more need the Perl sources around to compile Perl applications using the SDK: make sdkinstall The destination directory is C:\Symbian\perl\X.Y.Z. For more details, see F. Once the headers have been installed, you can create a SIS for the PerlApp: make perlapp.sis The perlapp.sis (11 kB -> 16 kB) will be built in the symbian subdirectory, but a copy will also be made to the main directory. If you want to package the Perl DLLs (one for WINS, one for ARMI), the headers, and the documentation: make perlsdk.zip which will create perlXYZsdk.zip that can be used in another Windows system with the SDK, without having to compile Perl in that system. If you want to package the PerlApp sources: make perlapp.zip If you want to package the perl.exe and miniperl.exe, you can use the perlexe.sis and miniperlexe.sis make targets. You also probably want the perllib.sis for the libraries and maybe even the perlapp.sis for the recognizer. The make target 'allsis' combines all the above SIS targets. To clean up after compilation you can use either of make clean make distclean depending on how clean you want to be. =head2 Compilation problems If you see right after "make" this cat makefile.sh >makefile 'cat' is not recognized as an internal or external command, operable program or batch file. it means you need to (re)run the F. If you get the error 'perl' is not recognized as an internal or external command, operable program or batch file. you may need to reinstall the ActivePerl. If you see this ren makedef.pl nomakedef.pl The system cannot find the file specified. C:\Symbian\...\make.exe: [rename_makedef] Error 1 (ignored) please ignore it since it is nothing serious (the build process of renames the Perl makedef.pl as nomakedef.pl to avoid confusing it with a makedef.pl of the SDK). =head2 PerlApp The PerlApp application demonstrates how to embed Perl interpreters to a Symbian application. The "Time" menu item runs the following Perl code: C, the "Oneliner" allows one to type in Perl code, and the "Run" opens a file chooser for selecting a Perl file to run. The PerlApp also is started when the "Perl recognizer" (also included and installed) detects a Perl file being activated through the GUI, and offers either to install it under \Perl (if the Perl file is in the inbox of the messaging application) or to run it (if the Perl file is under \Perl). =head2 sisify.pl In the symbian subdirectory there is F utility which can be used to package Perl scripts and/or Perl library directories into SIS files, which can be installed to the device. To run the sisify.pl utility, you will need to have the 'makesis' and 'uidcrc' utilities already installed. If you don't have the Win32 SDKs, you may try for example L or L. =head2 Using Perl in Symbian First of all note that you have full access to the Symbian device when using Perl: you can do a lot of damage to your device (like removing system files) unless you are careful. Please do take backups before doing anything. The Perl port has been done for the most part using the Symbian standard POSIX-ish STDLIB library. It is a reasonably complete library, but certain corners of such emulation libraries that tend to be left unimplemented on non-UNIX platforms have been left unimplemented also this time: fork(), signals(), user/group ids, select() working for sockets, non-blocking sockets, and so forth. See the file F and look for 'undef' to find the unsupported APIs (or from Perl use Config). The filesystem of Symbian devices uses DOSish syntax, "drives" separated from paths by a colon, and backslashes for the path. The exact assignment of the drives probably varies between platforms, but for example in Series 60 you might see C: as the (flash) main memory, D: as the RAM drive, E: as the memory card (MMC), Z: as the ROM. In Series 80 D: is the memory card. As far the devices go the NUL: is the bit bucket, the COMx: are the serial lines, IRCOMx: are the IR ports, TMP: might be C:\System\Temp. Remember to double those backslashes in doublequoted strings. The Perl DLL is installed in \System\Libs\. The Perl libraries and extension DLLs are installed in \System\Libs\Perl\X.Y.Z\. The PerlApp is installed in \System\Apps\, and the SIS also installs a couple of demo scripts in \Perl\ (C:\Mydocs\Perl\ on Nokia 7710). Note that the Symbian filesystem is very picky: it strongly prefers the \ instead of the /. When doing XS / Symbian C++ programming include first the Symbian headers, then any standard C/POSIX headers, then Perl headers, and finally any application headers. New() and Copy() are unfortunately used by both Symbian and Perl code so you'll have to play cpp games if you need them. PerlBase.h undefines the Perl definitions and redefines them as PerlNew() and PerlCopy(). =head1 TO DO Lots. See F. =head1 WARNING As of Perl Symbian port version 0.4.1 any part of Perl's standard regression test suite has not been run on a real Symbian device using the ported Perl, so innumerable bugs may lie in wait. Therefore there is absolutely no warranty. =head1 NOTE When creating and extending application programming interfaces (APIs) for Symbian or Series 60 or Series 80 or Series 90 it is suggested that trademarks, registered trademarks, or trade names are not used in the API names. Instead, developers should consider basing the API naming in the existing (C++, or maybe Java) public component and API naming, modified as appropriate by the rules of the programming language the new APIs are for. Nokia is a registered trademark of Nokia Corporation. Nokia's product names are trademarks or registered trademarks of Nokia. Other product and company names mentioned herein may be trademarks or trade names of their respective owners. =head1 AUTHOR Jarkko Hietaniemi =head1 COPYRIGHT Copyright (c) 2004-2005 Nokia. All rights reserved. Copyright (c) 2006-2007 Jarkko Hietaniemi. =head1 LICENSE The Symbian port is licensed under the same terms as Perl itself. =head1 HISTORY =over 4 =item * 0.1.0: April 2005 (This will show as "0.01" in the Symbian Installer.) - The console window is a very simple console indeed: one can get the newline with "000" and the "C" button is a backspace. Do not expect a terminal capable of vt100 or ANSI sequences. The console is also "ASCII", you cannot input e.g. any accented letters. Because of obvious physical constraints the console is also very small: (in Nokia 6600) 22 columns, 17 rows. - The following libraries are available: AnyDBM_File AutoLoader base Carp Config Cwd constant DynaLoader Exporter File::Spec integer lib strict Symbol vars warnings XSLoader - The following extensions are available: attributes Compress::Zlib Cwd Data::Dumper Devel::Peek Digest::MD5 DynaLoader Fcntl File::Glob Filter::Util::Call IO List::Util MIME::Base64 PerlIO::scalar PerlIO::via SDBM_File Socket Storable Time::HiRes - The following extensions are missing for various technical reasons: B ByteLoader Devel::DProf Devel::PPPort Encode GDBM_File I18N::Langinfo IPC::SysV NDBM_File Opcode PerlIO::encoding POSIX re Safe Sys::Hostname Sys::Syslog threads threads::shared Unicode::Normalize - Using MakeMaker or the Module::* to build and install modules is not supported. - Building XS other than the ones in the core is not supported. Since this is 0.something release, any future releases are almost guaranteed to be binary incompatible. As a sign of this the Symbian symbol exports are kept unfrozen and the .def files fully rebuilt every time. =item * 0.2.0: October 2005 - Perl 5.9.3 (patch level 25741) - Compress::Zlib and IO::Zlib supported - sisify.pl added We maintain the binary incompatibility. =item * 0.3.0: October 2005 - Perl 5.9.3 (patch level 25911) - Series 80 2.0 and UIQ 2.1 support We maintain the binary incompatibility. =item * 0.4.0: November 2005 - Perl 5.9.3 (patch level 26052) - adding a sample Symbian extension We maintain the binary incompatibility. =item * 0.4.1: December 2006 - Perl 5.9.5-to-be (patch level 30002) - added extensions: Compress/Raw/Zlib, Digest/SHA, Hash/Util, Math/BigInt/FastCalc, Text/Soundex, Time/Piece - port to S90 1.1 by alexander smishlajev We maintain the binary incompatibility. =item * 0.4.2: March 2007 - catchup with Perl 5.9.5-to-be (patch level 30812) - tested to build with Microsoft Visual C++ 2005 Express Edition (which uses Microsoft Visual C 8, instead of the old VC6), SDK used for testing S60_2nd_FP3 aka 8.1a We maintain the binary incompatibility. =back =cut ======================================================================== * cpan/Compress-Raw-Bzip2/README ======================================================================== Compress-Raw-Bzip2 Version 2.048 29th January 2012 Copyright (c) 2005-2012 Paul Marquess. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The directory bzip2-src contains a subset of the source files copied directly from bzip2 version 1.0.6. These files are Copyright(C) 1996-2010 Julian Seward. See the file bzip2-src/LICENSE for licence details for these files. Full source for the bzip2 library is available at http://www.bzip.org/ Note that the files bzip2.c, bzip2recover.c, bzlib.c & decompress.c have been modified to allow them to build with a C++ compiler. The file bzip2-src/bzip2-cpp.patch contains the patch that was used to modify the original source. DESCRIPTION ----------- Compress-Raw-Bzip2 provides the interface to the bzip2 library for the modules IO::Compress::Bzip2 and IO::Compress::Bunzip2. PREREQUISITES ------------- Before you can build Compress-Raw-Bzip2 you need to have the following installed on your system: * A C compiler * Perl 5.004 or better. BUILDING THE MODULE ------------------- Assuming you have met all the prerequisites, the module can now be built using this sequence of commands: perl Makefile.PL make make test INSTALLATION ------------ To install Compress-Raw-Bzip2, run the command below: make install TROUBLESHOOTING --------------- Solaris build fails with "language optional software package not installed" --------------------------------------------------------------------------- If you are trying to build this module under Solaris and you get an error message like this /usr/ucb/cc: language optional software package not installed it means that Perl cannot find the C compiler on your system. The cryptic message is just Sun's way of telling you that you haven't bought their C compiler. When you build a Perl module that needs a C compiler, the Perl build system tries to use the same C compiler that was used to build perl itself. In this case your Perl binary was built with a C compiler that lived in /usr/ucb. To continue with building this module, you need to get a C compiler, or tell Perl where your C compiler is, if you already have one. Assuming you have now got a C compiler, what you do next will be dependent on what C compiler you have installed. If you have just installed Sun's C compiler, you shouldn't have to do anything. Just try rebuilding this module. If you have installed another C compiler, say gcc, you have to tell perl how to use it instead of /usr/ucb/cc. This set of options seems to work if you want to use gcc. Your mileage may vary. perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" " make test If that doesn't work for you, it's time to make changes to the Makefile by hand. Good luck! Solaris build fails with "gcc: unrecognized option `-KPIC'" ----------------------------------------------------------- You are running Solaris and you get an error like this when you try to build this Perl module gcc: unrecognized option `-KPIC' This symptom usually means that you are using a Perl binary that has been built with the Sun C compiler, but you are using gcc to build this module. When Perl builds modules that need a C compiler, it will attempt to use the same C compiler and command line options that was used to build perl itself. In this case "-KPIC" is a valid option for the Sun C compiler, but not for gcc. The equivalent option for gcc is "-fPIC". The solution is either: 1. Build both Perl and this module with the same C compiler, either by using the Sun C compiler for both or gcc for both. 2. Try generating the Makefile for this module like this perl perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" " LD=gcc make test This second option seems to work when mixing a Perl binary built with the Sun C compiler and this module built with gcc. Your mileage may vary. HP-UX Notes ----------- I've had a report that when building Compress-Raw-Bzip2 under HP-UX that it is necessary to have first built the bzip2 library with the -fpic option. FEEDBACK -------- How to report a problem with Compress-Raw-Bzip2. To help me help you, I need all of the following information: 1. The Versions of everything relevant. This includes: a. The *complete* output from running this perl -V Do not edit the output in any way. Note, I want you to run "perl -V" and NOT "perl -v". If your perl does not understand the "-V" option it is too old. This module needs Perl version 5.004 or better. b. The version of Compress-Raw-Bzip2 you have. If you have successfully installed Compress-Raw-Bzip2, this one-liner will tell you: perl -MCompress::Raw::Bzip2 -e 'print qq[ver $Compress::Raw::Bzip2::VERSION\n]' If you are running windows use this perl -MCompress::Raw::Bzip2 -e "print qq[ver $Compress::Raw::Bzip2::VERSION\n]" If you haven't installed Compress-Raw-Bzip2 then search Compress::Raw::Bzip2.pm for a line like this: $VERSION = "2.048" ; c. The version of bzip2 you have used. If you have successfully installed Compress-Raw-Bzip2, this one-liner will tell you: perl -MCompress::Raw::Bzip2 -e "print q[bzip2 ver ]. Compress::Raw::Bzip2::ZLIB_VERSION.qq[\n]" If not, look at the beginning of the file zlib.h. 2. If you are having problems building Compress-Raw-Bzip2, send me a complete log of what happened. Start by unpacking the Compress-Raw-Bzip2 module into a fresh directory and keep a log of all the steps [edit config.in, if necessary] perl Makefile.PL make make test TEST_VERBOSE=1 Paul Marquess ======================================================================== * cpan/Compress-Raw-Zlib/README ======================================================================== Compress-Raw-Zlib Version 2.048 29th January 2012 Copyright (c) 2005-2012 Paul Marquess. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The directory zlib-src contains a subset of the source files copied directly from zlib version 1.2.5. These files are Copyright(C) 1995-2010 Jean-loup Gailly and Mark Adler. Full source for the zlib library is available at http://www.zlib.org DESCRIPTION ----------- This module provides a Perl interface to the zlib compression library. PREREQUISITES ------------- Before you can build Compress-Raw-Zlib you need to have the following installed on your system: * A C compiler * Perl 5.004 or better. By default, Compress-Raw-Zlib will build its own private copy of the zlib library. If you want to use a different version of zlib, follow the instructions in the section called "Controlling the version of zlib used by Compress-Raw-Zlib" later in this document. BUILDING THE MODULE ------------------- Assuming you have met all the prerequisites, the module can now be built using this sequence of commands: perl Makefile.PL make make test INSTALLATION ------------ To install Compress-Raw-Zlib, run the command below: make install Controlling the version of zlib used by Compress-Raw-Zlib ---------------------------------------------------------- Compress-Raw-Zlib interfaces to the zlib compression library. There are three options available to control which version/instance of the zlib library is used: 1. Build a private copy of the zlib library using the zlib library source that is included with this module. This is the default and recommended option. 2. Build a private copy of the zlib library using a standard zlib source distribution. 3. Use a pre-built zlib library. Note that if you intend to use either Option 2 or 3, you need to have zlib version 1.2.0 or better. The contents of the file config.in are used to control which of the three options is actually used. This file is read during the perl Makefile.PL step of the build, so remember to make any required changes to config.in before building this module. Option 1 -------- For option 1, edit the file config.in and set the variables in it as follows: BUILD_ZLIB = True INCLUDE = ./zlib-src LIB = ./zlib-src OLD_ZLIB = False GZIP_OS_CODE = AUTO_DETECT Option 2 -------- For option 2, fetch a copy of the zlib source distribution from http://www.zlib.org and unpack it into the Compress-Raw-Zlib source directory. Assuming you have fetched zlib 1.2.5, it will create a directory called zlib-1.2.5. Now set the variables in the file config.in as follows (if the version you have fetched isn't 1.2.5, change the INCLUDE and LIB variables appropriately): BUILD_ZLIB = True INCLUDE = ./zlib-1.2.5 LIB = ./zlib-1.2.5 OLD_ZLIB = False GZIP_OS_CODE = AUTO_DETECT Option 3 -------- For option 3, you need to find out where zlib is stored on your system. There are two parts to this. First, find the directory where the zlib library is stored (some common names for the library are libz.a and libz.so). Set the LIB variable in the config.in file to that directory. Secondly, find the directory where the file zlib.h is stored. Now set the INCLUDE variable in the config.in file to that directory. Next set BUILD_ZLIB to False. Finally, if you are running zlib 1.0.5 or older, set the OLD_ZLIB variable to True. Otherwise set it to False. As an example, if the zlib library on your system is in /usr/local/lib, zlib.h is in /usr/local/include and zlib is more recent than version 1.0.5, the variables in config.in should be set as follows: BUILD_ZLIB = False INCLUDE = /usr/local/include LIB = /usr/local/lib OLD_ZLIB = False GZIP_OS_CODE = AUTO_DETECT Setting the Gzip OS Code ------------------------ Every gzip stream stores a byte in its header to identify the Operating System that was used to create the gzip stream. When you build Compress-Raw-Zlib it will attempt to determine the value that is correct for your Operating System. This will then be used by IO::Compress::Gzip as the default value for the OS byte in all gzip headers it creates. The variable GZIP_OS_CODE in the config.in file controls the setting of this value when building Compress-Raw-Zlib. If GZIP_OS_CODE is set to AUTO_DETECT, Compress-Raw-Zlib will attempt to determine the correct value for your Operating System. Alternatively, you can override auto-detection of the default OS code and explicitly set it yourself. Set the GZIP_OS_CODE variable in the config.in file to be a number between 0 and 255. For example GZIP_OS_CODE = 3 See RFC 1952 for valid OS codes that can be used. If you are running one of the less popular Operating Systems, it is possible that the default value picked by this module is incorrect or the default value (3) is used when there is a better value available. When Compress-Raw-Zlib cannot determine what operating system you are running, it will use the default value 3 for the OS code. If you find you have to change this value, because you think the value auto detected is incorrect, please take a few moments to contact the author of this module. TROUBLESHOOTING --------------- Undefined Symbol gzsetparams ---------------------------- If you get the error shown below when you run the Compress-Raw-Zlib test harness it probably means you are running a copy of zlib that is version 1.0.5 or older. t/01version.........Can't load 'blib/arch/auto/Compress/Zlib/Zlib.so' for module Compress::Raw::Zlib: blib/arch/auto/Compress/Raw/Zlib/Zlib.so: undefined symbol: gzsetparams at ... There are two ways to fix this problem: 1. Upgrade to the latest version of zlib. 2. Edit config.in and set the OLD_ZLIB variable to True. Test Harness 01version fails ---------------------------- If the 01version test harness fails, and the problem isn't covered by the scenario above, it probably means that you have two versions of zlib installed on your system. Run the command below to see if this is indeed the case make test TEST_VERBOSE=1 TEST_FILES=t/01version.t Try removing the one you don't want to use and rebuild. Solaris build fails with "language optional software package not installed" --------------------------------------------------------------------------- If you are trying to build this module under Solaris and you get an error message like this /usr/ucb/cc: language optional software package not installed it means that Perl cannot find the C compiler on your system. The cryptic message is just Sun's way of telling you that you haven't bought their C compiler. When you build a Perl module that needs a C compiler, the Perl build system tries to use the same C compiler that was used to build perl itself. In this case your Perl binary was built with a C compiler that lived in /usr/ucb. To continue with building this module, you need to get a C compiler, or tell Perl where your C compiler is, if you already have one. Assuming you have now got a C compiler, what you do next will be dependent on what C compiler you have installed. If you have just installed Sun's C compiler, you shouldn't have to do anything. Just try rebuilding this module. If you have installed another C compiler, say gcc, you have to tell perl how to use it instead of /usr/ucb/cc. This set of options seems to work if you want to use gcc. Your mileage may vary. perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" " make test If that doesn't work for you, it's time to make changes to the Makefile by hand. Good luck! Solaris build fails with "gcc: unrecognized option `-KPIC'" ----------------------------------------------------------- You are running Solaris and you get an error like this when you try to build this Perl module gcc: unrecognized option `-KPIC' This symptom usually means that you are using a Perl binary that has been built with the Sun C compiler, but you are using gcc to build this module. When Perl builds modules that need a C compiler, it will attempt to use the same C compiler and command line options that was used to build perl itself. In this case "-KPIC" is a valid option for the Sun C compiler, but not for gcc. The equivalent option for gcc is "-fPIC". The solution is either: 1. Build both Perl and this module with the same C compiler, either by using the Sun C compiler for both or gcc for both. 2. Try generating the Makefile for this module like this perl perl Makefile.PL CC=gcc CCCDLFLAGS=-fPIC OPTIMIZE=" " LD=gcc make test This second option seems to work when mixing a Perl binary built with the Sun C compiler and this module built with gcc. Your mileage may vary. HP-UX Notes ----------- I've had a report that when building Compress-Raw-Zlib under HP-UX that it is necessary to have first built the zlib library with the -fpic option. Linux Notes ----------- Although most Linux distributions already come with zlib, some people report getting this error when they try to build this module: $ make cp Zlib.pm blib/lib/Compress/Zlib.pm AutoSplitting blib/lib/Compress/Zlib.pm (blib/lib/auto/Compress/Zlib) /usr/bin/perl -I/usr/lib/perl5/5.6.1/i386-linux -I/usr/lib/perl5/5.6.1 /usr/lib/perl5/5.6.1/ExtUtils/xsubpp -typemap /usr/lib/perl5/5.6.1/ExtUtils/typemap -typemap typemap Zlib.xs > Zlib.xsc && mv Zlib.xsc Zlib.c gcc -c -I/usr/local/include -fno-strict-aliasing -I/usr/local/include -O2 -march=i386 -mcpu=i686 -DVERSION=\"1.16\" -DXS_VERSION=\"1.16\" -fPIC -I/usr/lib/perl5/5.6.1/i386-linux/CORE Zlib.c Zlib.xs:25:19: zlib.h: No such file or directory make: *** [Zlib.o] Error 1 This usually means that you have not installed the development RPM for zlib. Check for an RPM that start with "zlib-devel" in your Linux distribution. Win32 Notes ----------- If you are running Activestate Perl (from http://www.activestate.com), it ships with a pre-compiled version of Compress-Raw-Zlib. To check if a newer version of Compress-Raw-Zlib is available run this from the command prompt C:\> ppm verify -upgrade Compress-Raw-Zlib If you are not running Activestate Perl and you don't have access to a C compiler, you will not be able to build and install this module. Win32 & Cygwin Notes -------------------- It is not possible to install Compress-Raw-Zlib using the CPAN shell. This is because the Compress-Raw-Zlib DLL is itself used by the CPAN shell and it is impossible to remove a DLL while it is already loaded under Windows. The workaround is to install Compress-Raw-Zlib manually using the instructions given at the start of this file. FEEDBACK -------- How to report a problem with Compress-Raw-Zlib. To help me help you, I need all of the following information: 1. The Versions of everything relevant. This includes: a. The *complete* output from running this perl -V Do not edit the output in any way. Note, I want you to run "perl -V" and NOT "perl -v". If your perl does not understand the "-V" option it is too old. This module needs Perl version 5.004 or better. b. The version of Compress-Raw-Zlib you have. If you have successfully installed Compress-Raw-Zlib, this one-liner will tell you: perl -MCompress::Raw::Zlib -e 'print qq[ver $Compress::Raw::Zlib::VERSION\n]' If you are running windows use this perl -MCompress::Raw::Zlib -e "print qq[ver $Compress::Raw::Zlib::VERSION\n]" If you haven't installed Compress-Raw-Zlib then search Compress::Raw::Zlib.pm for a line like this: $VERSION = "2.048" ; c. The version of zlib you have used. If you have successfully installed Compress-Raw-Zlib, this one-liner will tell you: perl -MCompress::Raw::Zlib -e "print q[zlib ver ]. Compress::Raw::Zlib::ZLIB_VERSION.qq[\n]" If not, look at the beginning of the file zlib.h. 2. If you are having problems building Compress-Raw-Zlib, send me a complete log of what happened. Start by unpacking the Compress-Raw-Zlib module into a fresh directory and keep a log of all the steps [edit config.in, if necessary] perl Makefile.PL make make test TEST_VERBOSE=1 Paul Marquess ======================================================================== * cpan/Devel-PPPort/README ======================================================================== ------------------------------------------------------ Devel::PPPort - Perl/Pollution/Portability Version 3 ------------------------------------------------------ CONTENTS 1. DESCRIPTION 2. INSTALLATION 3. DOCUMENTATION 4. BUGS 5. COPYRIGHT -------------- 1. DESCRIPTION -------------- Perl's API has changed over time, gaining new features, new functions, increasing its flexibility, and reducing the impact on the C namespace environment (reduced pollution). The header file written by this module, typically F, attempts to bring some of the newer Perl API features to older versions of Perl, so that you can worry less about keeping track of old releases, but users can still reap the benefit. --------------- 2. INSTALLATION --------------- Installation of the Devel::PPPort module follows the standard Perl Way and should not be harder than: perl Makefile.PL make make test make install Note that you may need to become superuser to 'make install'. If you're building the module under Windows, you may need to use a different make program, such as 'nmake', instead of 'make'. ---------------- 3. DOCUMENTATION ---------------- To see the documentation, use the perldoc command: perldoc Devel::PPPort You can also visit CPAN Search and see the documentation online as pretty nice HTML. This is also where you will find the most recent version of this module: http://search.cpan.org/~mhx/Devel-PPPort/ ------- 4. BUGS ------- If you find any bugs, Devel::PPPort doesn't seem to build on your system or any of its tests fail, please use the CPAN Request Tracker http://rt.cpan.org/ to create a ticket for the module. ------------ 5. COPYRIGHT ------------ Version 3.x, Copyright (C) 2004-2010, Marcus Holland-Moritz. Version 2.x, Copyright (C) 2001, Paul Marquess. Version 1.x, Copyright (C) 1999, Kenneth Albanowski. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ======================================================================== * cpan/Digest-MD5/README ======================================================================== The Digest::MD5 module allows you to use the RSA Data Security Inc. MD5 Message Digest algorithm from within Perl programs. The algorithm takes as input a message of arbitrary length and produces as output a 128-bit "fingerprint" or "message digest" of the input. MD5 is described in RFC 1321. You will need perl version 5.8 or better to install this module. Copyright 1998-2003 Gisle Aas. Copyright 1995-1996 Neil Winton. Copyright 1990-1992 RSA Data Security, Inc. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ======================================================================== * cpan/Digest-SHA/README ======================================================================== Digest::SHA version 5.71 ======================== Digest::SHA is a complete implementation of the NIST Secure Hash Standard. It gives Perl programmers a convenient way to calculate SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224, and SHA-512/256 message digests. The module can handle all types of input, including partial-byte data. Digest::SHA is written in C for speed. If your platform lacks a C compiler, you can install the functionally-equivalent (but much slower) Digest::SHA::PurePerl module. The tests subdirectory (t/*.t) contains an extensive set of SHA vectors compiled from various sources. INSTALLATION To install this module type the following: perl Makefile.PL [ options ] make make test make install The Makefile.PL options are: -t : build a thread-safe version of module -x : exclude support for SHA-384/512 DEPENDENCIES None COPYRIGHT AND LICENSE Copyright (C) 2003-2012 Mark Shelor This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Please refer to the Perl Artistic License for details: http://search.cpan.org/perldoc?perlartistic ======================================================================== * cpan/Encode/Encode/README.e2x ======================================================================== Encode::$_Name_ version 0.1 ======== NAME Encode::$_Name_ - SYNOPSIS use Encode::$_Name_; # ABSTRACT INSTALLATION To install this module type the following: perl Makefile.PL make make test make install DEPENDENCIES This module requires perl version 5.7.3 or later. COPYRIGHT AND LICENCE Copyright (C) 2002 Your Name This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ======================================================================== * cpan/Getopt-Long/README ======================================================================== Module Getopt::Long - extended processing of command line options ================================================================= Module Getopt::Long implements an extended getopt function called GetOptions(). This function implements the POSIX standard for command line options, with GNU extensions, while still capable of handling the traditional one-letter options. In general, this means that command line options can have long names instead of single letters, and are introduced with a double dash `--'. Optionally, Getopt::Long can support the traditional bundling of single-letter command line options. Getopt::Long is part of the Perl 5 distribution. It is the successor of newgetopt.pl that came with Perl 4. It is fully upward compatible. In fact, the Perl 5 version of newgetopt.pl is just a wrapper around the module. For complete documentation, see the Getopt::Long POD document or use the command perldoc Getopt::Long FEATURES ======== * Long option names Major advantage of using long option names is that it is much easier to memorize the option names. Using single-letter names one quickly runs into the problem that there is no logical relationship between the semantics of the selected option and its option letter. Disadvantage is that it requires more typing. Getopt::Long provides for option name abbreviation, so option names may be abbreviated to uniqueness. Also, modern shells like Cornell's tcsh support option name completion. As a rule of thumb, you can use abbreviations freely while running commands interactively but always use the full names in scripts. Examples (POSIX): --long --width=80 --height=24 Extensions: -long (convenience) +width=80 (deprecated) -height 24 (traditional) By default, long option names are case insensitive. * Single-letter options and bundling When single-letter options are requested, Getopt::Long allows the option names to be bundled, e.g. "-abc" is equivalent to "-a -b -c". In this case, long option names must be introduced with the POSIX "--" introducer. Examples: -lgAd (bundle) -xw 80 (bundle, w takes a value) -xw80 (same) even -l24w80 (l = 24 and w = 80) By default, single-letter option names are case sensitive. * Flexibility: - options can have alternative names, using an alternative name will behave as if the primary name was used; - options can be negatable, e.g. "debug" will switch it on, while "nodebug" will switch it off. - options can set values, but also add values producing an array of values instead of a single scalar value, or set values in a hash. - options can have multiple values, e.g., "--position 25 624". * Options linkage Using Getopt::Long gives the programmer ultimate control over the command line options and how they must be handled: - by setting a global variable in the calling program; - by setting a specified variable; - by entering the option name and the value in an associative array (hash) or object (if it is a blessed hash); - by calling a user-specified subroutine with the option name and the value as arguments (for hash options: the name, key and value); - combinations of the above. * Customization: The module can be customized by specifying settings in the 'use' directive, or by calling a special method, Getopt::Long::Configure. For example, the following two cases are functionally equal: use Getopt::Long qw(:config bundling no_ignore_case); and use Getopt::Long; Getopt::Long::Configure qw(bundling no_ignore_case); Some of the possible customizations. Most of them take a "no_" prefix to reverse the effect: - default Restore default settings. - auto_abbrev Allow option names to be abbreviated to uniqueness. - getopt_compat Allow '+' to start options. - gnu_compat Compatibility with GNU getopt_long(). - permute - require_order Whether non-options are allowed to be mixed with options. permute means that -foo arg1 -bar arg2 arg3 is equivalent to -foo -bar arg1 arg2 arg3 (provided -foo does not take an argument value). require_order means that options processing terminates when the first non-option is encountered. -foo arg1 -bar arg2 arg3 is equivalent to -foo -- arg1 -bar arg2 arg3 - bundling Setting this variable to a non-zero value will allow single-character options to be bundled. To distinguish bundles from long option names, long options must be introduced with "--" and single-character options (and bundles) with "-". - ignore_case Ignore case when matching options. - pass_through Do not issue error messages for unknown options, but leave them (pass-through) in @ARGV. - prefix The string that starts options. See also prefix_pattern. - prefix_pattern A Perl pattern that identifies the strings that introduce options. Default is --|-|\+ unless environment variable POSIXLY_CORRECT has been set, in which case it is --|-. - long_prefix_pattern A perl pattern that is used to identify which prefixes should be treated as long style. Any prefixes that don't match this pattern will have short option semantics. Defaults to --. - debug Enable copious debugging output. * Object oriented interface: Using the object oriented interface, multiple parser objects can be instantiated, each having their own configuration settings: $p1 = new Getopt::Long::Parser (config => ["bundling"]); $p2 = new Getopt::Long::Parser (config => ["posix"]); if ($p1->getoptions(...options descriptions...)) ... AVAILABILITY ============ The official version for module Getopt::Long comes with the Perl 5 distribution. Newer versions will be made available on the Comprehensive Perl Archive Network (CPAN), see "http://www.perl.com/CPAN/authors/Johan_Vromans". Or use the CPAN search engine: http://search.cpan.org/search?mode=module&query=Getopt::Long http://search.cpan.org/search?module=Getopt::Long COPYRIGHT AND DISCLAIMER ======================== Module Getopt::Long is Copyright 2009,1990 by Johan Vromans. This program is free software; you can redistribute it and/or modify it under the terms of the Perl Artistic License or the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. ------------------------------------------------------------------- Johan Vromans jvromans@squirrel.nl Squirrel Consultancy Exloo, the Netherlands http://www.squirrel.nl http://www.squirrel.nl/people/jvromans ------------------ "Arms are made for hugging" -------------------- ======================================================================== * cpan/IO-Compress/README ======================================================================== IO-Compress Version 2.048 29th January 2012 Copyright (c) 1995-2012 Paul Marquess. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. DESCRIPTION ----------- This distribution provides a Perl interface to allow reading and writing of compressed data created with the zlib and bzip2 libraries. IO-Compress supports reading and writing of bzip2, RFC 1950, RFC 1951, RFC 1952 (i.e. gzip) and zip files/buffers. The following modules used to be distributed separately, but are now included with the IO-Compress distribution. Compress-Zlib IO-Compress-Zlib IO-Compress-Bzip2 IO-Compress-Base PREREQUISITES ------------- Before you can build IO-Compress you need to have the following installed on your system: * Perl 5.004 or better. * Compress::Raw::Zlib * Compress::Raw::Bzip2 BUILDING THE MODULE ------------------- Assuming you have met all the prerequisites, the module can now be built using this sequence of commands: perl Makefile.PL make make test INSTALLATION ------------ To install IO-Compress, run the command below: make install TROUBLESHOOTING --------------- FEEDBACK -------- How to report a problem with IO-Compress. To help me help you, I need all of the following information: 1. The Versions of everything relevant. This includes: a. The *complete* output from running this perl -V Do not edit the output in any way. Note, I want you to run "perl -V" and NOT "perl -v". If your perl does not understand the "-V" option it is too old. This module needs Perl version 5.004 or better. b. The version of IO-Compress you have. If you have successfully installed IO-Compress, this one-liner will tell you: perl -MIO::Compress::Gzip -e 'print qq[ver $IO::Compress::Gzip::VERSION\n]' If you are running windows use this perl -MIO::Compress::Gzip -e "print qq[ver $IO::Compress::Gzip::VERSION\n]" If you haven't installed IO-Compress then search IO::Compress::Gzip.pm for a line like this: $VERSION = "2.048" ; 2. If you are having problems building IO-Compress, send me a complete log of what happened. Start by unpacking the IO-Compress module into a fresh directory and keep a log of all the steps [edit config.in, if necessary] perl Makefile.PL make make test TEST_VERBOSE=1 Paul Marquess ======================================================================== * cpan/IPC-SysV/README ======================================================================== Version 2.x, Copyright (C) 2007-2010, Marcus Holland-Moritz. Version 1.x, Copyright (c) 1997, Graham Barr. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The SysV-IPC contains three packages IPC::Semaphore - Provides an object interface to using SysV IPC semaphores IPC::Msg - Provides an object interface to using SysV IPC messages IPC::SysV - Provides the constants required to use the system SysV IPC calls. Currently there is not object support for SysV shared memory, but SysV::SharedMem is a project for the future. Share and enjoy! ======================================================================== * cpan/List-Util/README ======================================================================== This distribution is a replacement for the builtin distribution. This package contains a selection of subroutines that people have expressed would be nice to have in the perl core, but the usage would not really be high enough to warrant the use of a keyword, and the size so small such that being individual extensions would be wasteful. After unpacking the distribution, to install this module type perl Makefile.PL make make test make install KNOWN BUGS There is a bug in perl5.6.0 with UV's that are >= 1<<31. This will show up as tests 8 and 9 of dualvar.t failing Copyright (c) 1997-2006 Graham Barr . All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ======================================================================== * cpan/MIME-Base64/README ======================================================================== This package contains a base64 encoder/decoder and a quoted-printable encoder/decoder. These encoding methods are specified in RFC 2045 - MIME (Multipurpose Internet Mail Extensions). The base64 encoding is designed to represent arbitrary sequences of octets in a form that need not be humanly readable. A 65-character subset ([A-Za-z0-9+/=]) of US-ASCII is used, enabling 6 bits to be represented per printable character. The quoted-printable encoding is intended to represent data that largely consists of bytes that correspond to printable characters in the ASCII character set. Each non-printable character is represented by a triplet consisting of the character "=" followed by two hexadecimal digits. In order to install and use this package you will need Perl version 5.6 or better. Installation as usual: perl Makefile.PL make make test make install Copyright 1995-1999,2001-2004,2010 Gisle Aas This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ======================================================================== * cpan/Pod-Simple/README ======================================================================== =head1 Pod::Simple version 3.20 Pod::Simple is a Perl library for parsing text in the Pod ("plain old documentation") markup language that is typically used for writing documentation for Perl and for Perl modules. The Pod format is explained L; the most common formatter is called C. Pod formatters can use Pod::Simple to parse Pod documents and render them into plain text, HTML, or any number of other formats. =head2 Installation To install this module, type the following: perl Makefile.PL make make test make install =head2 Support Questions or discussion about POD and Pod::Simple should be sent to the pod-people@perl.org mail list. Send an empty email to pod-people-subscribe@perl.org to subscribe. This module is managed in an open GitHub repository, L. Feel free to fork and contribute, or to clone L and send patches! Patches against Pod::Simple are welcome. Please send bug reports to . =head1 copyright and Disclaimers Copyright (c) 2002 Sean M. Burke. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. =head1 Author Pod::Simple was created by Sean M. Burke . But don't bother him, he's retired. Pod::Simple is maintained by: =over =item * Allison Randal C =item * Hans Dieter Pearcey C =item * David E. Wheeler C =back =cut ======================================================================== * cpan/Sys-Syslog/README ======================================================================== NAME Sys::Syslog - Perl interface to the UNIX syslog(3) calls DESCRIPTION Sys::Syslog is an interface to the UNIX syslog(3) program. Call syslog() with a string priority and a list of printf() args just like syslog(3). INSTALLATION To install this module, run the following commands: $ perl Makefile.PL $ make $ make test $ make install An ANSI-compliant compiler is required to compile the extension. Sys::Syslog should work on any Perl since 5.6.0. This module has been tested by the author on the following Perl and system versions but is likely to run on many more: Perl Architecture GCC ----------------------------------------------------- 5.6.2 i686-linux 3.4.1 5.8.5 i386-linux-thread-multi 3.4.1 5.8.8 i386-freebsd-64int 3.4.4 5.8.6 darwin-thread-multi-2level (PowerPC) 4.0.1 See also the corresponding CPAN Testers page: http://testers.cpan.org/show/Sys-Syslog.html SUPPORT AND DOCUMENTATION After installing, you can find documentation for this module with the perldoc command. perldoc Sys::Syslog You can also look for information at: Search CPAN http://search.cpan.org/dist/Sys-Syslog/ Kobes' CPAN Search http://cpan.uwinnipeg.ca/dist/Sys-Syslog CPAN Request Tracker: http://rt.cpan.org/NoAuth/Bugs.html?Dist=Sys-Syslog AnnoCPAN, annotated CPAN documentation: http://annocpan.org/dist/Sys-Syslog CPAN Ratings: http://cpanratings.perl.org/d/Sys-Syslog COPYRIGHT AND LICENCE Copyright (C) 1990-2009 by Larry Wall and others. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ======================================================================== * cpan/Term-ANSIColor/README ======================================================================== Term::ANSIColor version 3.01 (A simple ANSI text attribute control module) Copyright 1996, 1997, 1998, 2000, 2001, 2002, 2005, 2006, 2007, 2009, 2010, 2011 Russ Allbery and Zenin. This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. I welcome bug reports and patches for this package at rra@stanford.edu. However, please be aware that I tend to be extremely busy and to get a lot of mail. I'll save your mail and get to it as soon as I can, but depending on how busy I am it may take me a couple of months. BLURB Term::ANSIColor provides constants and simple functions for sending ANSI text attributes, most notably colors. It can be used to set the current text attributes or to apply a set of attributes to a string and reset the current text attributes at the end of that string. DESCRIPTION This module grew out of a thread on comp.lang.perl.misc where several of us were throwing around different ways to print colored text from Perl scripts and Zenin posted his old library to do that. I (Russ) disagreed with the implementation and offered my own (the color() and colored() functions implemented in this package), Zenin convinced me that the constants had their place as well, and we started figuring out the best ways of implementing both. While ANSI color escape codes are fairly simple, it can be hard to remember the codes for all of the attributes and the code resulting from hard-coding them into your script is definitely difficult to read. This module is designed to fix those problems, as well as provide a convenient interface to do a few things for you automatically (like resetting attributes after the text you print out so that you don't accidentally leave attributes set). Despite its name, this module can also handle non-color ANSI text attributes (bold, underline, reverse video, and blink). It uses either of two interfaces, one of which uses "constants" for each different attribute and the other of which uses two subs which take strings of attributes as arguments. See the POD documentation for complete details, features, and usage. This module is distributed as part of the Perl core distribution as of Perl 5.6.0. You only need to install this module if you want a newer version than came with Perl or if you have an old version of Perl. REQUIREMENTS Term::ANSIColor is written in pure Perl and has no module dependencies that aren't found in Perl core. It should work with any version of Perl after 5.001, although it hasn't been tested with old versions in some time. The test suite requires the Test::More module. To check the POD documentation, Test::Pod is also required. To check spelling, Pod::Spell and either aspell or ispell with the american dictionary are also required. The user's path is searched for aspell or ispell and aspell is preferred. Spelling tests are disabled by default since spelling dictionaries differ too much between systems. To enable those tests, set RRA_MAINTAINER_TESTS to a true value. INSTALLATION WARNING: Installation of this package will replace the Term::ANSIColor that came with Perl for Perl 5.6.0 or later. Term::ANSIColor that came with Perl. You may want to save a backup copy of the standard version first. Follow the standard installation procedure for Perl modules, which is to type the following commands: perl Makefile.PL make make test make install You'll probably need to do the last as root. If instead you wish to install the module by hand, simply copy it into a directory named Term in your Perl library directory. HOMEPAGE AND SOURCE REPOSITORY The Term::ANSIColor web page at: http://www.eyrie.org/~eagle/software/ansicolor/ will always have the current version of this package, the current documentation, and pointers to any additional resources. Term::ANSIColor is maintained using Git. You can access the current source by cloning the repository at: git://git.eyrie.org/perl/ansicolor.git or view the repository on the web at: http://git.eyrie.org/?p=perl/ansicolor.git THANKS To Jon Lennox for looking at early versions of this module, providing feedback, and offering suggestions for improvement. To Jesse Taylor for writing the first significant script to use this module (colorized calsplit), thus offering innumerable opportunities to test and debug. To Jean Delvare for providing documentation of what the various attributes do on various different terminal emulators, and for noting that attribute 2 is dark. To Edward Avis for the implementation of uncolor. To Rani Pinchuk for the idea of ANSI_COLORS_DISABLED and an initial implementation. To ATricket for the information about what PuTTY, Windows telnet, and OpenSSH under Cygwin support. To Richard Maus for pointing out DARK was missing from the exported constants list and CYAN and WHITE were missing from the documentation. To Autrijus Tang for noticing a problem with string comparisons in the test suite. To Daniel Lindsley for the information about what Mac OS X Terminal supports. To Joe Smith for the test files that exercise a wide variety of VT100 escape sequences including the ECMA-48 color control codes. To James Bowlin for catching a bug in colored when $EACHLINE is set that caused it to not color lines consisting solely of 0. To Helge Kreutzmann for pointing out the need for warnings in the documentation about background colors that span newlines. To Baron Schwartz for pointing out that cyan and white were missing from the documentation. To Michael R. Wolf for pointing out that Wikipedia and the ECMA standard use faint instead of dark as the name of attribute 2. To openmethods.com voice solutions for contributing PUSHCOLOR, POPCOLOR, and LOCALCOLOR support. To Tim Bellinghausen for the AUTOLOAD taint fix for Perl 5.10. To Paul Miller for the idea and initial implementation of colorstrip. To Jakob Ilves for sixteen-color support and the initial documentation of bright color issues. To Revilo Reegiles for reporting problems with the colored function and non-array references with stringification defined, and providing a test case. To Larry Wall, as always, for Perl. ======================================================================== * cpan/Text-Balanced/README ======================================================================== NAME Text::Balanced - Extract delimited text sequences from strings. SYNOPSIS use Text::Balanced qw ( extract_delimited extract_bracketed extract_quotelike extract_codeblock extract_variable extract_tagged extract_multiple gen_delimited_pat gen_extract_tagged ); # Extract the initial substring of $text that is delimited by # two (unescaped) instances of the first character in $delim. ($extracted, $remainder) = extract_delimited($text,$delim); # Extract the initial substring of $text that is bracketed # with a delimiter(s) specified by $delim (where the string # in $delim contains one or more of '(){}[]<>'). ($extracted, $remainder) = extract_bracketed($text,$delim); # Extract the initial substring of $text that is bounded by # an XML tag. ($extracted, $remainder) = extract_tagged($text); # Extract the initial substring of $text that is bounded by # a C...C pair. Don't allow nested C tags ($extracted, $remainder) = extract_tagged($text,"BEGIN","END",undef,{bad=>["BEGIN"]}); # Extract the initial substring of $text that represents a # Perl "quote or quote-like operation" ($extracted, $remainder) = extract_quotelike($text); # Extract the initial substring of $text that represents a block # of Perl code, bracketed by any of character(s) specified by $delim # (where the string $delim contains one or more of '(){}[]<>'). ($extracted, $remainder) = extract_codeblock($text,$delim); # Extract the initial substrings of $text that would be extracted by # one or more sequential applications of the specified functions # or regular expressions @extracted = extract_multiple($text, [ \&extract_bracketed, \&extract_quotelike, \&some_other_extractor_sub, qr/[xyz]*/, 'literal', ]); # Create a string representing an optimized pattern (a la Friedl) # that matches a substring delimited by any of the specified characters # (in this case: any type of quote or a slash) $patstring = gen_delimited_pat(q{'"`/}); # Generate a reference to an anonymous sub that is just like extract_tagged # but pre-compiled and optimized for a specific pair of tags, and consequently # much faster (i.e. 3 times faster). It uses qr// for better performance on # repeated calls, so it only works under Perl 5.005 or later. $extract_head = gen_extract_tagged('',''); ($extracted, $remainder) = $extract_head->($text); DESCRIPTION The various "extract_..." subroutines may be used to extract a delimited substring, possibly after skipping a specified prefix string. By default, that prefix is optional whitespace ("/\s*/"), but you can change it to whatever you wish (see below). The substring to be extracted must appear at the current "pos" location of the string's variable (or at index zero, if no "pos" position is defined). In other words, the "extract_..." subroutines *don't* extract the first occurrence of a substring anywhere in a string (like an unanchored regex would). Rather, they extract an occurrence of the substring appearing immediately at the current matching position in the string (like a "\G"-anchored regex would). General behaviour in list contexts In a list context, all the subroutines return a list, the first three elements of which are always: [0] The extracted string, including the specified delimiters. If the extraction fails "undef" is returned. [1] The remainder of the input string (i.e. the characters after the extracted string). On failure, the entire string is returned. [2] The skipped prefix (i.e. the characters before the extracted string). On failure, "undef" is returned. Note that in a list context, the contents of the original input text (the first argument) are not modified in any way. However, if the input text was passed in a variable, that variable's "pos" value is updated to point at the first character after the extracted text. That means that in a list context the various subroutines can be used much like regular expressions. For example: while ( $next = (extract_quotelike($text))[0] ) { # process next quote-like (in $next) } General behaviour in scalar and void contexts In a scalar context, the extracted string is returned, having first been removed from the input text. Thus, the following code also processes each quote-like operation, but actually removes them from $text: while ( $next = extract_quotelike($text) ) { # process next quote-like (in $next) } Note that if the input text is a read-only string (i.e. a literal), no attempt is made to remove the extracted text. In a void context the behaviour of the extraction subroutines is exactly the same as in a scalar context, except (of course) that the extracted substring is not returned. A note about prefixes Prefix patterns are matched without any trailing modifiers ("/gimsox" etc.) This can bite you if you're expecting a prefix specification like '.*?(?=

)' to skip everything up to the first

tag. Such a prefix pattern will only succeed if the

tag is on the current line, since . normally doesn't match newlines. To overcome this limitation, you need to turn on /s matching within the prefix pattern, using the "(?s)" directive: '(?s).*?(?=

)' "extract_delimited" The "extract_delimited" function formalizes the common idiom of extracting a single-character-delimited substring from the start of a string. For example, to extract a single-quote delimited string, the following code is typically used: ($remainder = $text) =~ s/\A('(\\.|[^'])*')//s; $extracted = $1; but with "extract_delimited" it can be simplified to: ($extracted,$remainder) = extract_delimited($text, "'"); "extract_delimited" takes up to four scalars (the input text, the delimiters, a prefix pattern to be skipped, and any escape characters) and extracts the initial substring of the text that is appropriately delimited. If the delimiter string has multiple characters, the first one encountered in the text is taken to delimit the substring. The third argument specifies a prefix pattern that is to be skipped (but must be present!) before the substring is extracted. The final argument specifies the escape character to be used for each delimiter. All arguments are optional. If the escape characters are not specified, every delimiter is escaped with a backslash ("\"). If the prefix is not specified, the pattern '\s*' - optional whitespace - is used. If the delimiter set is also not specified, the set "/["'`]/" is used. If the text to be processed is not specified either, $_ is used. In list context, "extract_delimited" returns a array of three elements, the extracted substring (*including the surrounding delimiters*), the remainder of the text, and the skipped prefix (if any). If a suitable delimited substring is not found, the first element of the array is the empty string, the second is the complete original text, and the prefix returned in the third element is an empty string. In a scalar context, just the extracted substring is returned. In a void context, the extracted substring (and any prefix) are simply removed from the beginning of the first argument. Examples: # Remove a single-quoted substring from the very beginning of $text: $substring = extract_delimited($text, "'", ''); # Remove a single-quoted Pascalish substring (i.e. one in which # doubling the quote character escapes it) from the very # beginning of $text: $substring = extract_delimited($text, "'", '', "'"); # Extract a single- or double- quoted substring from the # beginning of $text, optionally after some whitespace # (note the list context to protect $text from modification): ($substring) = extract_delimited $text, q{"'}; # Delete the substring delimited by the first '/' in $text: $text = join '', (extract_delimited($text,'/','[^/]*')[2,1]; Note that this last example is *not* the same as deleting the first quote-like pattern. For instance, if $text contained the string: "if ('./cmd' =~ m/$UNIXCMD/s) { $cmd = $1; }" then after the deletion it would contain: "if ('.$UNIXCMD/s) { $cmd = $1; }" not: "if ('./cmd' =~ ms) { $cmd = $1; }" See "extract_quotelike" for a (partial) solution to this problem. "extract_bracketed" Like "extract_delimited", the "extract_bracketed" function takes up to three optional scalar arguments: a string to extract from, a delimiter specifier, and a prefix pattern. As before, a missing prefix defaults to optional whitespace and a missing text defaults to $_. However, a missing delimiter specifier defaults to '{}()[]<>' (see below). "extract_bracketed" extracts a balanced-bracket-delimited substring (using any one (or more) of the user-specified delimiter brackets: '(..)', '{..}', '[..]', or '<..>'). Optionally it will also respect quoted unbalanced brackets (see below). A "delimiter bracket" is a bracket in list of delimiters passed as "extract_bracketed"'s second argument. Delimiter brackets are specified by giving either the left or right (or both!) versions of the required bracket(s). Note that the order in which two or more delimiter brackets are specified is not significant. A "balanced-bracket-delimited substring" is a substring bounded by matched brackets, such that any other (left or right) delimiter bracket *within* the substring is also matched by an opposite (right or left) delimiter bracket *at the same level of nesting*. Any type of bracket not in the delimiter list is treated as an ordinary character. In other words, each type of bracket specified as a delimiter must be balanced and correctly nested within the substring, and any other kind of ("non-delimiter") bracket in the substring is ignored. For example, given the string: $text = "{ an '[irregularly :-(] {} parenthesized >:-)' string }"; then a call to "extract_bracketed" in a list context: @result = extract_bracketed( $text, '{}' ); would return: ( "{ an '[irregularly :-(] {} parenthesized >:-)' string }" , "" , "" ) since both sets of '{..}' brackets are properly nested and evenly balanced. (In a scalar context just the first element of the array would be returned. In a void context, $text would be replaced by an empty string.) Likewise the call in: @result = extract_bracketed( $text, '{[' ); would return the same result, since all sets of both types of specified delimiter brackets are correctly nested and balanced. However, the call in: @result = extract_bracketed( $text, '{([<' ); would fail, returning: ( undef , "{ an '[irregularly :-(] {} parenthesized >:-)' string }" ); because the embedded pairs of '(..)'s and '[..]'s are "cross-nested" and the embedded '>' is unbalanced. (In a scalar context, this call would return an empty string. In a void context, $text would be unchanged.) Note that the embedded single-quotes in the string don't help in this case, since they have not been specified as acceptable delimiters and are therefore treated as non-delimiter characters (and ignored). However, if a particular species of quote character is included in the delimiter specification, then that type of quote will be correctly handled. for example, if $text is: $text = 'link'; then @result = extract_bracketed( $text, '<">' ); returns: ( '', 'link', "" ) as expected. Without the specification of """ as an embedded quoter: @result = extract_bracketed( $text, '<>' ); the result would be: ( 'link', "" ) In addition to the quote delimiters "'", """, and "`", full Perl quote-like quoting (i.e. q{string}, qq{string}, etc) can be specified by including the letter 'q' as a delimiter. Hence: @result = extract_bracketed( $text, '' ); would correctly match something like this: $text = ''; See also: "extract_quotelike" and "extract_codeblock". "extract_variable" "extract_variable" extracts any valid Perl variable or variable-involved expression, including scalars, arrays, hashes, array accesses, hash look-ups, method calls through objects, subroutine calls through subroutine references, etc. The subroutine takes up to two optional arguments: 1. A string to be processed ($_ if the string is omitted or "undef") 2. A string specifying a pattern to be matched as a prefix (which is to be skipped). If omitted, optional whitespace is skipped. On success in a list context, an array of 3 elements is returned. The elements are: [0] the extracted variable, or variablish expression [1] the remainder of the input text, [2] the prefix substring (if any), On failure, all of these values (except the remaining text) are "undef". In a scalar context, "extract_variable" returns just the complete substring that matched a variablish expression. "undef" is returned on failure. In addition, the original input text has the returned substring (and any prefix) removed from it. In a void context, the input text just has the matched substring (and any specified prefix) removed. "extract_tagged" "extract_tagged" extracts and segments text between (balanced) specified tags. The subroutine takes up to five optional arguments: 1. A string to be processed ($_ if the string is omitted or "undef") 2. A string specifying a pattern to be matched as the opening tag. If the pattern string is omitted (or "undef") then a pattern that matches any standard XML tag is used. 3. A string specifying a pattern to be matched at the closing tag. If the pattern string is omitted (or "undef") then the closing tag is constructed by inserting a "/" after any leading bracket characters in the actual opening tag that was matched (*not* the pattern that matched the tag). For example, if the opening tag pattern is specified as '{{\w+}}' and actually matched the opening tag "{{DATA}}", then the constructed closing tag would be "{{/DATA}}". 4. A string specifying a pattern to be matched as a prefix (which is to be skipped). If omitted, optional whitespace is skipped. 5. A hash reference containing various parsing options (see below) The various options that can be specified are: "reject => $listref" The list reference contains one or more strings specifying patterns that must *not* appear within the tagged text. For example, to extract an HTML link (which should not contain nested links) use: extract_tagged($text, '', '', undef, {reject => ['']} ); "ignore => $listref" The list reference contains one or more strings specifying patterns that are *not* be be treated as nested tags within the tagged text (even if they would match the start tag pattern). For example, to extract an arbitrary XML tag, but ignore "empty" elements: extract_tagged($text, undef, undef, undef, {ignore => ['<[^>]*/>']} ); (also see "gen_delimited_pat" below). "fail => $str" The "fail" option indicates the action to be taken if a matching end tag is not encountered (i.e. before the end of the string or some "reject" pattern matches). By default, a failure to match a closing tag causes "extract_tagged" to immediately fail. However, if the string value associated with is "MAX", then "extract_tagged" returns the complete text up to the point of failure. If the string is "PARA", "extract_tagged" returns only the first paragraph after the tag (up to the first line that is either empty or contains only whitespace characters). If the string is "", the the default behaviour (i.e. failure) is reinstated. For example, suppose the start tag "/para" introduces a paragraph, which then continues until the next "/endpara" tag or until another "/para" tag is encountered: $text = "/para line 1\n\nline 3\n/para line 4"; extract_tagged($text, '/para', '/endpara', undef, {reject => '/para', fail => MAX ); # EXTRACTED: "/para line 1\n\nline 3\n" Suppose instead, that if no matching "/endpara" tag is found, the "/para" tag refers only to the immediately following paragraph: $text = "/para line 1\n\nline 3\n/para line 4"; extract_tagged($text, '/para', '/endpara', undef, {reject => '/para', fail => MAX ); # EXTRACTED: "/para line 1\n" Note that the specified "fail" behaviour applies to nested tags as well. On success in a list context, an array of 6 elements is returned. The elements are: [0] the extracted tagged substring (including the outermost tags), [1] the remainder of the input text, [2] the prefix substring (if any), [3] the opening tag [4] the text between the opening and closing tags [5] the closing tag (or "" if no closing tag was found) On failure, all of these values (except the remaining text) are "undef". In a scalar context, "extract_tagged" returns just the complete substring that matched a tagged text (including the start and end tags). "undef" is returned on failure. In addition, the original input text has the returned substring (and any prefix) removed from it. In a void context, the input text just has the matched substring (and any specified prefix) removed. "gen_extract_tagged" (Note: This subroutine is only available under Perl5.005) "gen_extract_tagged" generates a new anonymous subroutine which extracts text between (balanced) specified tags. In other words, it generates a function identical in function to "extract_tagged". The difference between "extract_tagged" and the anonymous subroutines generated by "gen_extract_tagged", is that those generated subroutines: * do not have to reparse tag specification or parsing options every time they are called (whereas "extract_tagged" has to effectively rebuild its tag parser on every call); * make use of the new qr// construct to pre-compile the regexes they use (whereas "extract_tagged" uses standard string variable interpolation to create tag-matching patterns). The subroutine takes up to four optional arguments (the same set as "extract_tagged" except for the string to be processed). It returns a reference to a subroutine which in turn takes a single argument (the text to be extracted from). In other words, the implementation of "extract_tagged" is exactly equivalent to: sub extract_tagged { my $text = shift; $extractor = gen_extract_tagged(@_); return $extractor->($text); } (although "extract_tagged" is not currently implemented that way, in order to preserve pre-5.005 compatibility). Using "gen_extract_tagged" to create extraction functions for specific tags is a good idea if those functions are going to be called more than once, since their performance is typically twice as good as the more general-purpose "extract_tagged". "extract_quotelike" "extract_quotelike" attempts to recognize, extract, and segment any one of the various Perl quotes and quotelike operators (see perlop(3)) Nested backslashed delimiters, embedded balanced bracket delimiters (for the quotelike operators), and trailing modifiers are all caught. For example, in: extract_quotelike 'q # an octothorpe: \# (not the end of the q!) #' extract_quotelike ' "You said, \"Use sed\"." ' extract_quotelike ' s{([A-Z]{1,8}\.[A-Z]{3})} /\L$1\E/; ' extract_quotelike ' tr/\\\/\\\\/\\\//ds; ' the full Perl quotelike operations are all extracted correctly. Note too that, when using the /x modifier on a regex, any comment containing the current pattern delimiter will cause the regex to be immediately terminated. In other words: 'm / (?i) # CASE INSENSITIVE [a-z_] # LEADING ALPHABETIC/UNDERSCORE [a-z0-9]* # FOLLOWED BY ANY NUMBER OF ALPHANUMERICS /x' will be extracted as if it were: 'm / (?i) # CASE INSENSITIVE [a-z_] # LEADING ALPHABETIC/' This behaviour is identical to that of the actual compiler. "extract_quotelike" takes two arguments: the text to be processed and a prefix to be matched at the very beginning of the text. If no prefix is specified, optional whitespace is the default. If no text is given, $_ is used. In a list context, an array of 11 elements is returned. The elements are: [0] the extracted quotelike substring (including trailing modifiers), [1] the remainder of the input text, [2] the prefix substring (if any), [3] the name of the quotelike operator (if any), [4] the left delimiter of the first block of the operation, [5] the text of the first block of the operation (that is, the contents of a quote, the regex of a match or substitution or the target list of a translation), [6] the right delimiter of the first block of the operation, [7] the left delimiter of the second block of the operation (that is, if it is a "s", "tr", or "y"), [8] the text of the second block of the operation (that is, the replacement of a substitution or the translation list of a translation), [9] the right delimiter of the second block of the operation (if any), [10] the trailing modifiers on the operation (if any). For each of the fields marked "(if any)" the default value on success is an empty string. On failure, all of these values (except the remaining text) are "undef". In a scalar context, "extract_quotelike" returns just the complete substring that matched a quotelike operation (or "undef" on failure). In a scalar or void context, the input text has the same substring (and any specified prefix) removed. Examples: # Remove the first quotelike literal that appears in text $quotelike = extract_quotelike($text,'.*?'); # Replace one or more leading whitespace-separated quotelike # literals in $_ with "" do { $_ = join '', (extract_quotelike)[2,1] } until $@; # Isolate the search pattern in a quotelike operation from $text ($op,$pat) = (extract_quotelike $text)[3,5]; if ($op =~ /[ms]/) { print "search pattern: $pat\n"; } else { print "$op is not a pattern matching operation\n"; } "extract_quotelike" and "here documents" "extract_quotelike" can successfully extract "here documents" from an input string, but with an important caveat in list contexts. Unlike other types of quote-like literals, a here document is rarely a contiguous substring. For example, a typical piece of code using here document might look like this: <<'EOMSG' || die; This is the message. EOMSG exit; Given this as an input string in a scalar context, "extract_quotelike" would correctly return the string "<<'EOMSG'\nThis is the message.\nEOMSG", leaving the string " || die;\nexit;" in the original variable. In other words, the two separate pieces of the here document are successfully extracted and concatenated. In a list context, "extract_quotelike" would return the list [0] "<<'EOMSG'\nThis is the message.\nEOMSG\n" (i.e. the full extracted here document, including fore and aft delimiters), [1] " || die;\nexit;" (i.e. the remainder of the input text, concatenated), [2] "" (i.e. the prefix substring -- trivial in this case), [3] "<<" (i.e. the "name" of the quotelike operator) [4] "'EOMSG'" (i.e. the left delimiter of the here document, including any quotes), [5] "This is the message.\n" (i.e. the text of the here document), [6] "EOMSG" (i.e. the right delimiter of the here document), [7..10] "" (a here document has no second left delimiter, second text, second right delimiter, or trailing modifiers). However, the matching position of the input variable would be set to "exit;" (i.e. *after* the closing delimiter of the here document), which would cause the earlier " || die;\nexit;" to be skipped in any sequence of code fragment extractions. To avoid this problem, when it encounters a here document whilst extracting from a modifiable string, "extract_quotelike" silently rearranges the string to an equivalent piece of Perl: <<'EOMSG' This is the message. EOMSG || die; exit; in which the here document *is* contiguous. It still leaves the matching position after the here document, but now the rest of the line on which the here document starts is not skipped. To prevent from mucking about with the input in this way (this is the only case where a list-context "extract_quotelike" does so), you can pass the input variable as an interpolated literal: $quotelike = extract_quotelike("$var"); "extract_codeblock" "extract_codeblock" attempts to recognize and extract a balanced bracket delimited substring that may contain unbalanced brackets inside Perl quotes or quotelike operations. That is, "extract_codeblock" is like a combination of "extract_bracketed" and "extract_quotelike". "extract_codeblock" takes the same initial three parameters as "extract_bracketed": a text to process, a set of delimiter brackets to look for, and a prefix to match first. It also takes an optional fourth parameter, which allows the outermost delimiter brackets to be specified separately (see below). Omitting the first argument (input text) means process $_ instead. Omitting the second argument (delimiter brackets) indicates that only '{' is to be used. Omitting the third argument (prefix argument) implies optional whitespace at the start. Omitting the fourth argument (outermost delimiter brackets) indicates that the value of the second argument is to be used for the outermost delimiters. Once the prefix an dthe outermost opening delimiter bracket have been recognized, code blocks are extracted by stepping through the input text and trying the following alternatives in sequence: 1. Try and match a closing delimiter bracket. If the bracket was the same species as the last opening bracket, return the substring to that point. If the bracket was mismatched, return an error. 2. Try to match a quote or quotelike operator. If found, call "extract_quotelike" to eat it. If "extract_quotelike" fails, return the error it returned. Otherwise go back to step 1. 3. Try to match an opening delimiter bracket. If found, call "extract_codeblock" recursively to eat the embedded block. If the recursive call fails, return an error. Otherwise, go back to step 1. 4. Unconditionally match a bareword or any other single character, and then go back to step 1. Examples: # Find a while loop in the text if ($text =~ s/.*?while\s*\{/{/) { $loop = "while " . extract_codeblock($text); } # Remove the first round-bracketed list (which may include # round- or curly-bracketed code blocks or quotelike operators) extract_codeblock $text, "(){}", '[^(]*'; The ability to specify a different outermost delimiter bracket is useful in some circumstances. For example, in the Parse::RecDescent module, parser actions which are to be performed only on a successful parse are specified using a "" directive. For example: sentence: subject verb object Parse::RecDescent uses "extract_codeblock($text, '{}<>')" to extract the code within the "" directive, but there's a problem. A deferred action like this: 10) {$count--}} > will be incorrectly parsed as: because the "less than" operator is interpreted as a closing delimiter. But, by extracting the directive using "extract_codeblock($text, '{}', undef, '<>')" the '>' character is only treated as a delimited at the outermost level of the code block, so the directive is parsed correctly. "extract_multiple" The "extract_multiple" subroutine takes a string to be processed and a list of extractors (subroutines or regular expressions) to apply to that string. In an array context "extract_multiple" returns an array of substrings of the original string, as extracted by the specified extractors. In a scalar context, "extract_multiple" returns the first substring successfully extracted from the original string. In both scalar and void contexts the original string has the first successfully extracted substring removed from it. In all contexts "extract_multiple" starts at the current "pos" of the string, and sets that "pos" appropriately after it matches. Hence, the aim of of a call to "extract_multiple" in a list context is to split the processed string into as many non-overlapping fields as possible, by repeatedly applying each of the specified extractors to the remainder of the string. Thus "extract_multiple" is a generalized form of Perl's "split" subroutine. The subroutine takes up to four optional arguments: 1. A string to be processed ($_ if the string is omitted or "undef") 2. A reference to a list of subroutine references and/or qr// objects and/or literal strings and/or hash references, specifying the extractors to be used to split the string. If this argument is omitted (or "undef") the list: [ sub { extract_variable($_[0], '') }, sub { extract_quotelike($_[0],'') }, sub { extract_codeblock($_[0],'{}','') }, ] is used. 3. An number specifying the maximum number of fields to return. If this argument is omitted (or "undef"), split continues as long as possible. If the third argument is *N*, then extraction continues until *N* fields have been successfully extracted, or until the string has been completely processed. Note that in scalar and void contexts the value of this argument is automatically reset to 1 (under "-w", a warning is issued if the argument has to be reset). 4. A value indicating whether unmatched substrings (see below) within the text should be skipped or returned as fields. If the value is true, such substrings are skipped. Otherwise, they are returned. The extraction process works by applying each extractor in sequence to the text string. If the extractor is a subroutine it is called in a list context and is expected to return a list of a single element, namely the extracted text. It may optionally also return two further arguments: a string representing the text left after extraction (like $' for a pattern match), and a string representing any prefix skipped before the extraction (like $` in a pattern match). Note that this is designed to facilitate the use of other Text::Balanced subroutines with "extract_multiple". Note too that the value returned by an extractor subroutine need not bear any relationship to the corresponding substring of the original text (see examples below). If the extractor is a precompiled regular expression or a string, it is matched against the text in a scalar context with a leading '\G' and the gc modifiers enabled. The extracted value is either $1 if that variable is defined after the match, or else the complete match (i.e. $&). If the extractor is a hash reference, it must contain exactly one element. The value of that element is one of the above extractor types (subroutine reference, regular expression, or string). The key of that element is the name of a class into which the successful return value of the extractor will be blessed. If an extractor returns a defined value, that value is immediately treated as the next extracted field and pushed onto the list of fields. If the extractor was specified in a hash reference, the field is also blessed into the appropriate class, If the extractor fails to match (in the case of a regex extractor), or returns an empty list or an undefined value (in the case of a subroutine extractor), it is assumed to have failed to extract. If none of the extractor subroutines succeeds, then one character is extracted from the start of the text and the extraction subroutines reapplied. Characters which are thus removed are accumulated and eventually become the next field (unless the fourth argument is true, in which case they are discarded). For example, the following extracts substrings that are valid Perl variables: @fields = extract_multiple($text, [ sub { extract_variable($_[0]) } ], undef, 1); This example separates a text into fields which are quote delimited, curly bracketed, and anything else. The delimited and bracketed parts are also blessed to identify them (the "anything else" is unblessed): @fields = extract_multiple($text, [ { Delim => sub { extract_delimited($_[0],q{'"}) } }, { Brack => sub { extract_bracketed($_[0],'{}') } }, ]); This call extracts the next single substring that is a valid Perl quotelike operator (and removes it from $text): $quotelike = extract_multiple($text, [ sub { extract_quotelike($_[0]) }, ], undef, 1); Finally, here is yet another way to do comma-separated value parsing: @fields = extract_multiple($csv_text, [ sub { extract_delimited($_[0],q{'"}) }, qr/([^,]+)(.*)/, ], undef,1); The list in the second argument means: *"Try and extract a ' or " delimited string, otherwise extract anything up to a comma..."*. The undef third argument means: *"...as many times as possible..."*, and the true value in the fourth argument means *"...discarding anything else that appears (i.e. the commas)"*. If you wanted the commas preserved as separate fields (i.e. like split does if your split pattern has capturing parentheses), you would just make the last parameter undefined (or remove it). "gen_delimited_pat" The "gen_delimited_pat" subroutine takes a single (string) argument and > builds a Friedl-style optimized regex that matches a string delimited by any one of the characters in the single argument. For example: gen_delimited_pat(q{'"}) returns the regex: (?:\"(?:\\\"|(?!\").)*\"|\'(?:\\\'|(?!\').)*\') Note that the specified delimiters are automatically quotemeta'd. A typical use of "gen_delimited_pat" would be to build special purpose tags for "extract_tagged". For example, to properly ignore "empty" XML elements (which might contain quoted strings): my $empty_tag = '<(' . gen_delimited_pat(q{'"}) . '|.)+/>'; extract_tagged($text, undef, undef, undef, {ignore => [$empty_tag]} ); "gen_delimited_pat" may also be called with an optional second argument, which specifies the "escape" character(s) to be used for each delimiter. For example to match a Pascal-style string (where ' is the delimiter and '' is a literal ' within the string): gen_delimited_pat(q{'},q{'}); Different escape characters can be specified for different delimiters. For example, to specify that '/' is the escape for single quotes and '%' is the escape for double quotes: gen_delimited_pat(q{'"},q{/%}); If more delimiters than escape chars are specified, the last escape char is used for the remaining delimiters. If no escape char is specified for a given specified delimiter, '\' is used. "delimited_pat" Note that "gen_delimited_pat" was previously called "delimited_pat". That name may still be used, but is now deprecated. DIAGNOSTICS In a list context, all the functions return "(undef,$original_text)" on failure. In a scalar context, failure is indicated by returning "undef" (in this case the input text is not modified in any way). In addition, on failure in *any* context, the $@ variable is set. Accessing "$@->{error}" returns one of the error diagnostics listed below. Accessing "$@->{pos}" returns the offset into the original string at which the error was detected (although not necessarily where it occurred!) Printing $@ directly produces the error message, with the offset appended. On success, the $@ variable is guaranteed to be "undef". The available diagnostics are: "Did not find a suitable bracket: "%s"" The delimiter provided to "extract_bracketed" was not one of '()[]<>{}'. "Did not find prefix: /%s/" A non-optional prefix was specified but wasn't found at the start of the text. "Did not find opening bracket after prefix: "%s"" "extract_bracketed" or "extract_codeblock" was expecting a particular kind of bracket at the start of the text, and didn't find it. "No quotelike operator found after prefix: "%s"" "extract_quotelike" didn't find one of the quotelike operators "q", "qq", "qw", "qx", "s", "tr" or "y" at the start of the substring it was extracting. "Unmatched closing bracket: "%c"" "extract_bracketed", "extract_quotelike" or "extract_codeblock" encountered a closing bracket where none was expected. "Unmatched opening bracket(s): "%s"" "extract_bracketed", "extract_quotelike" or "extract_codeblock" ran out of characters in the text before closing one or more levels of nested brackets. "Unmatched embedded quote (%s)" "extract_bracketed" attempted to match an embedded quoted substring, but failed to find a closing quote to match it. "Did not find closing delimiter to match '%s'" "extract_quotelike" was unable to find a closing delimiter to match the one that opened the quote-like operation. "Mismatched closing bracket: expected "%c" but found "%s"" "extract_bracketed", "extract_quotelike" or "extract_codeblock" found a valid bracket delimiter, but it was the wrong species. This usually indicates a nesting error, but may indicate incorrect quoting or escaping. "No block delimiter found after quotelike "%s"" "extract_quotelike" or "extract_codeblock" found one of the quotelike operators "q", "qq", "qw", "qx", "s", "tr" or "y" without a suitable block after it. "Did not find leading dereferencer" "extract_variable" was expecting one of '$', '@', or '%' at the start of a variable, but didn't find any of them. "Bad identifier after dereferencer" "extract_variable" found a '$', '@', or '%' indicating a variable, but that character was not followed by a legal Perl identifier. "Did not find expected opening bracket at %s" "extract_codeblock" failed to find any of the outermost opening brackets that were specified. "Improperly nested codeblock at %s" A nested code block was found that started with a delimiter that was specified as being only to be used as an outermost bracket. "Missing second block for quotelike "%s"" "extract_codeblock" or "extract_quotelike" found one of the quotelike operators "s", "tr" or "y" followed by only one block. "No match found for opening bracket" "extract_codeblock" failed to find a closing bracket to match the outermost opening bracket. "Did not find opening tag: /%s/" "extract_tagged" did not find a suitable opening tag (after any specified prefix was removed). "Unable to construct closing tag to match: /%s/" "extract_tagged" matched the specified opening tag and tried to modify the matched text to produce a matching closing tag (because none was specified). It failed to generate the closing tag, almost certainly because the opening tag did not start with a bracket of some kind. "Found invalid nested tag: %s" "extract_tagged" found a nested tag that appeared in the "reject" list (and the failure mode was not "MAX" or "PARA"). "Found unbalanced nested tag: %s" "extract_tagged" found a nested opening tag that was not matched by a corresponding nested closing tag (and the failure mode was not "MAX" or "PARA"). "Did not find closing tag" "extract_tagged" reached the end of the text without finding a closing tag to match the original opening tag (and the failure mode was not "MAX" or "PARA"). AUTHOR Damian Conway (damian@conway.org) BUGS AND IRRITATIONS There are undoubtedly serious bugs lurking somewhere in this code, if only because parts of it give the impression of understanding a great deal more about Perl than they really do. Bug reports and other feedback are most welcome. COPYRIGHT Copyright 1997 - 2001 Damian Conway. All Rights Reserved. Some (minor) parts copyright 2009 Adam Kennedy. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself. ======================================================================== * cpan/Unicode-Collate/README ======================================================================== Unicode/Collate version 0.89 =============================== NAME Unicode::Collate - Unicode Collation Algorithm SYNOPSIS use Unicode::Collate; #construct $Collator = Unicode::Collate->new(%tailoring); #sort @sorted = $Collator->sort(@not_sorted); #compare $result = $Collator->cmp($a, $b); # returns 1, 0, or -1. $result = $Collator->eq($a, $b); # returns true/false (similarly ->ne, ->lt, ->le, ->gt, ->ge) Note: Strings in @not_sorted, $a and $b are interpreted according to Perl's Unicode support. See perlunicode, perluniintro, perlunitut, perlunifaq, utf8. Otherwise you can use "preprocess" or should decode them before. INSTALL Perl 5.6.1 or later is required. Perl 5.8.1 or later is recommended. Though this distribution contains a subset of an old DUCET, named "keys.txt", this one is intended only for doing a test of this module and practically useless for any other purpose. Installation of Unicode::Collate::Locale requires Collate/Locale.pm, Collate/Locale/*.pm, Collate/CJK/*.pm and Collate/allkeys.txt. On building, Unicode::Collate::Locale doesn't require any of data/*.txt, gendata/*, and mklocale. Tests for Unicode::Collate::Locale are named t/loc_*.t. Since 0.54, XSUB that requires a C compiler will be built by default. To install this module type the following: perl Makefile.PL make make test make install Even if a C compiler is not available, pure Perl (i.e. non-XS) edition is available; type the following: perl disableXS perl Makefile.PL make make test make install If you decide to install XSUB edition after trying to build pure Perl, type the following: make clean perl enableXS perl Makefile.PL make make test make install DEPENDENCIES The conformant collation requires Unicode::Normalize (v 0.10 or later) although Unicode::Collate can be used without Unicode::Normalize. ABOUT DUCET Though this module can be used without any C file, to use this module easily, it is recommended to install a table file in the UCA format, by copying it under the directory /Unicode/Collate. You can install such a table file by adding it to "Collate" directory (where "keys.txt" is placed) in this distribution before executing Makefile.PL. The most preferable one is "The Default Unicode Collation Element Table" (aka DUCET), available from the Unicode Consortium's website: http://www.unicode.org/Public/UCA/ http://www.unicode.org/Public/UCA/latest/allkeys.txt (latest version) If DUCET is not installed, it is recommended to copy the file from http://www.unicode.org/Public/UCA/latest/allkeys.txt to /Unicode/Collate/allkeys.txt manually. HOW TO CHANGE DUCET (NOT WARRANTED) 0. rewriting UCA_Version and Base_Unicode_Version in Collate.pm and t/version.t is preferred. 1. replace Collate/allkeys.txt with a new DUCET. 2. run mklocale to generate new Locale/*.pl and Korean.pm. 3. replace Collate/Locale/*.pl with the new Locale/*.pl, and Collate/CJK/Korean.pm with the new Korean.pm. 4. make test. IF FAIL, it may require more changes, not be easy. AUTHOR, COPYRIGHT AND LICENSE The Unicode::Collate module for perl was written by SADAHIRO Tomoyuki, . This module is Copyright(C) 2001-2012, SADAHIRO Tomoyuki. Japan. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The file Unicode/Collate/allkeys.txt was copied verbatim from http://www.unicode.org/Public/UCA/6.1.0/allkeys.txt For this file, Copyright (c) 2001-2011 Unicode, Inc. Distributed under the Terms of Use in http://www.unicode.org/copyright.html ======================================================================== * cpan/Unicode-Normalize/README ======================================================================== Unicode/Normalize version 1.14 =================================== Unicode::Normalize - Unicode Normalization Forms SYNOPSIS (1) using function names exported by default: use Unicode::Normalize; $NFD_string = NFD($string); # Normalization Form D $NFC_string = NFC($string); # Normalization Form C $NFKD_string = NFKD($string); # Normalization Form KD $NFKC_string = NFKC($string); # Normalization Form KC (2) using function names exported on request: use Unicode::Normalize 'normalize'; $NFD_string = normalize('D', $string); # Normalization Form D $NFC_string = normalize('C', $string); # Normalization Form C $NFKD_string = normalize('KD', $string); # Normalization Form KD $NFKC_string = normalize('KC', $string); # Normalization Form KC INSTALLATION Perl 5.6.1 or later is required. Perl 5.8.1 or later is recommended. To install this module (XSUB: needs a C compiler), type the following: perl Makefile.PL make make test make install If you want to install pure Perl (i.e. no-XSUB), type the following (!! "disableXS" must run before "Makefile.PL" !!): perl disableXS perl Makefile.PL make make test make install After building no-XSUB, if you decide to install XSUB, type the following (!! "enableXS" must run before "Makefile.PL" !!): make clean perl enableXS perl Makefile.PL make make test make install DEPENDENCIES This module requires some core modules and pragmas, and the following files from Unicode Character Database, which are included in recent perl core distributions. - unicore/CombiningClass.pl (or unicode/CombiningClass.pl) - unicore/Decomposition.pl (or unicode/Decomposition.pl) NOTES (1) After these unicore/*.* files are updated: In the case of XSUB: You must rebuild the module, as the data will be compiled on building. In the case of pure perl: Rebuilding is not necessary, as the data will be read on requirement. (2) Normalize.pmN (a pure perl module) may work without any other file in this distribution. It must be renamed Normalize.pm, though. COPYRIGHT AND LICENSE SADAHIRO Tomoyuki Copyright(C) 2001-2012, SADAHIRO Tomoyuki. Japan. All rights reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ======================================================================== * cpan/libnet/README ======================================================================== libnet is a collection of Perl modules which provides a simple and consistent programming interface (API) to the client side of various protocols used in the internet community. For details of each protocol please refer to the RFC. RFC's can be found a various places on the WEB, for a starting point look at: http://www.yahoo.com/Computers_and_Internet/Standards/RFCs/ The RFC implemented in this distribution are Net::FTP RFC959 File Transfer Protocol Net::SMTP RFC821 Simple Mail Transfer Protocol Net::Time RFC867 Daytime Protocol Net::Time RFC868 Time Protocol Net::NNTP RFC977 Network News Transfer Protocol Net::POP3 RFC1939 Post Office Protocol 3 AVAILABILITY The latest version of libnet is available from the Comprehensive Perl Archive Network (CPAN). To find a CPAN site near you see: http://search.cpan.org/~gbarr/libnet/ The subversion source repository can be browsed at http://svn.goingon.net/viewvc/libnet/ If you have a subversion client, then you can checkout the latest code with svn co http://svn.goingon.net/repos/libnet/trunk libnet INSTALLATION In order to use this package you will need Perl version 5.002 or better. You install libnet, as you would install any perl module library, by running these commands: perl Makefile.PL make make test make install If you want to install a private copy of libnet in your home directory, then you should try to produce the initial Makefile with something like this command: perl Makefile.PL PREFIX=~/perl The Makefile.PL program will start out by checking your perl installation for a few packages that are recommended to be installed together with libnet. These packages should be available on CPAN (described above). CONFIGURE Normally when perl Makefile.PL is run it will run Configure which will ask some questions about your system. The results of these questions will be stored in a file called libnet.cfg which will be installed alongside the other perl modules in this distribution. The Makefile.PL will run Configure in an interactive mode unless these exists a file called libnet.cfg in the build directory. If you are on a system which cannot run this script you can create an empty file to make Makefile.PL skip running Configure. If you want to keep your existing settings and not run interactivly the simple run Configure -d before running the Makefile.PL. DOCUMENTATION See ChangeLog for recent changes. POD style documentation is included in all modules and scripts. These are normally converted to manual pages and installed as part of the "make install" process. You should also be able to use the 'perldoc' utility to extract documentation from the module files directly. DEMOS The demos directory does contain a few demo scripts. These should be run from the top directory like demos/smtp.self -user my-email-address -debug However I do not guarantee these scripts to work. SUPPORT Questions about how to use this library should be directed to the comp.lang.perl.modules USENET Newsgroup. Bug reports and suggestions for improvements can be sent to me at . Most of the modules in this library have an option to output a debug transcript to STDERR. When reporting bugs/problems please, if possible, include a transcript of a run. COPYRIGHT (C) 1996-2007 Graham Barr. All rights reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Share and Enjoy! ======================================================================== * dist/I18N-LangTags/README ======================================================================== README for I18N::LangTags Time-stamp: "2004-10-06 23:19:39 ADT" I18N::LangTags I18N::LangTags - functions for dealing with RFC3066-style language tags Language tags are a formalism, described in RFC 3066 (obsoleting 1766), for declaring what language form (language and possibly dialect) a given chunk of information is in. This library provides functions for common tasks involving language tags (notably the extraction of them, comparing them, and testing the formal validity of them) as is needed in a variety of protocols and applications. I18N::LangTags::List -- tags and names for human languages. This module goes from known language tag names ("fr-CA") to their English names ("Canadian French"). Its documentation also lists the several hundred known tags and some common subforms. You may find this useful as a reference. See the POD for more information. INSTALLATION You install I18N::LangTags and I18N::LangTags::List, as you would install any perl module library, by running these commands: perl Makefile.PL make make test make install If you want to install a private copy of I18N::LangTags in your home directory, then you should try to produce the initial Makefile with something like this command: perl Makefile.PL LIB=~/perl See perldoc perlmodinstall for more information on installing modules. DOCUMENTATION POD-format documentation is included in LangTags.pm. POD is readable with the 'perldoc' utility. See ChangeLog for recent changes. SUPPORT Questions, bug reports, useful code bits, and suggestions for I18N::LangTags should just be sent to me at sburke@cpan.org AVAILABILITY The latest version of I18N::LangTags is available from the Comprehensive Perl Archive Network (CPAN). Visit to find a CPAN site near you. COPYRIGHT Copyright 1998+, Sean M. Burke , all rights reserved. The programs and documentation in this dist are distributed in the hope that they will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ======================================================================== * dist/Locale-Maketext/README ======================================================================== README for Locale::Maketext Time-stamp: "2004-03-30 16:02:27 AST" Locale::Maketext Locale::Maketext is a base class providing a framework for localization and inheritance-based lexicons, as described in my article in The Perl Journal #13 (a corrected version of which appears in this dist). PREREQUISITES This suite requires Perl 5. It also requires a recent version of I18N::LangTags. MSWin users should also get Win32::Locale. File::Findgrep is also useful example code, as is the rather larger Apache::MP3 source (even if you don't run Apache). INSTALLATION You install Locale::Maketext, as you would install any Perl module distribution, by running these commands: perl Makefile.PL make make test make install If you want to install a private copy of Maketext in your home directory, then you should try to produce the initial Makefile with something like this command: perl Makefile.PL LIB=~/perl See perldoc perlmodinstall for more information. DOCUMENTATION See the pod in Locale::Maketext and Locale::Maketext::TPJ13, and see also File::Findgrep. SUPPORT Questions, bug reports, useful code bits, and suggestions for Worms should be sent to me at sburke@cpan.org AVAILABILITY The latest version of Locale::Maketext is available from the Comprehensive Perl Archive Network (CPAN). Visit to find a CPAN site near you. COPYRIGHT Copyright 1999-2004, Sean M. Burke , all rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AUTHOR Sean M. Burke ======================================================================== * dist/Module-CoreList/README ======================================================================== README for Module::CoreList 2.20 =head1 NAME Module::CoreList - what modules shipped with versions of perl =head1 SYNOPSIS use Module::CoreList; print $Module::CoreList::version{5.00503}{CPAN}; # prints 1.48 print Module::CoreList->first_release('File::Spec'); # prints 5.00503 print Module::CoreList->first_release('File::Spec', 0.82); # prints 5.006001 print join ", ", @{ $Module::CoreList::families{5.005} }; # prints "5.005, 5.00503, 5.00504" =head1 DEPENDENCIES This module has external dependencies on the following modules: Test::More =head1 INSTALLATION perl Makefile.PL make make test and if all goes well make install =head1 HISTORY See the F file. =head1 AUTHOR Richard Clamp Erichardc@unixbeard.netE Currently maintained by the perl 5 porters Eperl5-porters@perl.orgE. =head1 COPYRIGHT Copyright (C) 2002-2009 Richard Clamp. All Rights Reserved. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. =head1 SEE ALSO L, L ======================================================================== * dist/Storable/README ======================================================================== Storable 2.14 Copyright (c) 1995-2000, Raphael Manfredi Copyright (c) 2001-2004, Larry Wall ------------------------------------------------------------------------ This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the Perl 5 License schemes for more details. ------------------------------------------------------------------------ +======================================================================= | Storable is distributed as a module, but is also part of the official | Perl core distribution, as of perl 5.8. | Maintenance is now done by the perl5-porters. We thank Raphael | Manfredi for providing us with this very useful module. +======================================================================= The Storable extension brings persistence to your data. You may recursively store to disk any data structure, no matter how complex and circular it is, provided it contains only SCALAR, ARRAY, HASH (possibly tied) and references (possibly blessed) to those items. At a later stage, or in another program, you may retrieve data from the stored file and recreate the same hiearchy in memory. If you had blessed references, the retrieved references are blessed into the same package, so you must make sure you have access to the same perl class than the one used to create the relevant objects. There is also a dclone() routine which performs an optimized mirroring of any data structure, preserving its topology. Objects (blessed references) may also redefine the way storage and retrieval is performed, and/or what deep cloning should do on those objects. To compile this extension, run: perl Makefile.PL [PERL_SRC=...where you put perl sources...] make make install There is an embedded POD manual page in Storable.pm. Storable was written by Raphael Manfredi Maintenance is now done by the perl5-porters Please e-mail us with problems, bug fixes, comments and complaints, although if you have complements you should send them to Raphael. Please don't e-mail Raphael with problems, as he no longer works on Storable, and your message will be delayed while he forwards it to us. ------------------------------------------------------------------------ Thanks to (in chronological order): Jarkko Hietaniemi Ulrich Pfeifer Benjamin A. Holzman Andrew Ford Gisle Aas Jeff Gresham Murray Nesbitt Albert N. Micheev Marc Lehmann Justin Banks Jarkko Hietaniemi (AGAIN, as perl 5.7.0 Pumpkin!) for their contributions. A Japanese translation of this man page is available at the Japanized Perl Resources Project . ------------------------------------------------------------------------ The perl5-porters would like to thank Raphael Manfredi According to the perl5.8 Changes file, the following people have helped bring you this Storable release: Abhijit Menon-Sen Andreas J. Koenig Archer Sully Craig A. Berry Dan Kogai Doug MacEachern Gurusamy Sarathy H.Merijn Brand Jarkko Hietaniemi Mark Bixby Michael Stevens Mike Guy Nicholas Clark Peter J. Farley III Peter Prymmer Philip Newton Raphael Manfredi Robin Barker Radu Greab Tim Bunce VMSperlers Yitzchak Scott-Thoennes If I've missed you out, please accept my apologies, and e-mail your patch to perl5-porters@perl.org. ======================================================================== * ext/SDBM_File/sdbm/README ======================================================================== sdbm - Substitute DBM or Berkeley ndbm for Every UN*X[1] Made Simple Ozan (oz) Yigit The Guild of PD Software Toolmakers Toronto - Canada oz@nexus.yorku.ca Implementation is the sincerest form of flattery. - L. Peter Deutsch A The Clone of the ndbm library The sources accompanying this notice - sdbm - consti- tute the first public release (Dec. 1990) of a complete clone of the Berkeley UN*X ndbm library. The sdbm library is meant to clone the proven functionality of ndbm as closely as possible, including a few improvements. It is practical, easy to understand, and compatible. The sdbm library is not derived from any licensed, proprietary or copyrighted software. The sdbm implementation is based on a 1978 algorithm [Lar78] by P.-A. (Paul) Larson known as "Dynamic Hashing". In the course of searching for a substitute for ndbm, I pro- totyped three different external-hashing algorithms [Lar78, Fag79, Lit80] and ultimately chose Larson's algorithm as a basis of the sdbm implementation. The Bell Labs dbm (and therefore ndbm) is based on an algorithm invented by Ken Thompson, [Tho90, Tor87] and predates Larson's work. The sdbm programming interface is totally compatible with ndbm and includes a slight improvement in database ini- tialization. It is also expected to be binary-compatible under most UN*X versions that support the ndbm library. The sdbm implementation shares the shortcomings of the ndbm library, as a side effect of various simplifications to the original Larson algorithm. It does produce holes in the page file as it writes pages past the end of file. (Larson's paper include a clever solution to this problem that is a result of using the hash value directly as a block address.) On the other hand, extensive tests seem to indicate that sdbm creates fewer holes in general, and the resulting page- files are smaller. The sdbm implementation is also faster than ndbm in database creation. Unlike the ndbm, the sdbm _________________________ [1] UN*X is not a trademark of any (dis)organization. - 2 - store operation will not "wander away" trying to split its data pages to insert a datum that cannot (due to elaborate worst-case situations) be inserted. (It will fail after a pre-defined number of attempts.) Important Compatibility Warning The sdbm and ndbm libraries cannot share databases: one cannot read the (dir/pag) database created by the other. This is due to the differences between the ndbm and sdbm algorithms[2], and the hash functions used. It is easy to convert between the dbm/ndbm databases and sdbm by ignoring the index completely: see dbd, dbu etc. Notice of Intellectual Property The entire sdbm library package, as authored by me, Ozan S. Yigit, is hereby placed in the public domain. As such, the author is not responsible for the consequences of use of this software, no matter how awful, even if they arise from defects in it. There is no expressed or implied warranty for the sdbm library. Since the sdbm library package is in the public domain, this original release or any additional public-domain releases of the modified original cannot possibly (by defin- ition) be withheld from you. Also by definition, You (singu- lar) have all the rights to this code (including the right to sell without permission, the right to hoard[3] and the right to do other icky things as you see fit) but those rights are also granted to everyone else. Please note that all previous distributions of this software contained a copyright (which is now dropped) to protect its origins and its current public domain status against any possible claims and/or challenges. Acknowledgments Many people have been very helpful and supportive. A partial list would necessarily include Rayan Zacherissen (who contributed the man page, and also hacked a MMAP _________________________ [2] Torek's discussion [Tor87] indicates that dbm/ndbm implementations use the hash value to traverse the radix trie differently than sdbm and as a result, the page indexes are generated in different order. For more information, send e-mail to the author. [3] You cannot really hoard something that is avail- able to the public at large, but try if it makes you feel any better. - 3 - version of sdbm), Arnold Robbins, Chris Lewis, Bill David- sen, Henry Spencer, Geoff Collyer, Rich Salz (who got me started in the first place), Johannes Ruschein (who did the minix port) and David Tilbrook. I thank you all. Distribution Manifest and Notes This distribution of sdbm includes (at least) the following: CHANGES change log README this file. biblio a small bibliography on external hashing dba.c a crude (n/s)dbm page file analyzer dbd.c a crude (n/s)dbm page file dumper (for conversion) dbe.1 man page for dbe.c dbe.c Janick's database editor dbm.c a dbm library emulation wrapper for ndbm/sdbm dbm.h header file for the above dbu.c a crude db management utility hash.c hashing function makefile guess. pair.c page-level routines (posted earlier) pair.h header file for the above readme.ms troff source for the README file sdbm.3 man page sdbm.c the real thing sdbm.h header file for the above tune.h place for tuning & portability thingies util.c miscellaneous dbu is a simple database manipulation program[4] that tries to look like Bell Labs' cbt utility. It is currently incomplete in functionality. I use dbu to test out the rou- tines: it takes (from stdin) tab separated key/value pairs for commands like build or insert or takes keys for commands like delete or look. dbu dbmfile dba is a crude analyzer of dbm/sdbm/ndbm page files. It scans the entire page file, reporting page level statistics, and totals at the end. dbd is a crude dump program for dbm/ndbm/sdbm data- bases. It ignores the bitmap, and dumps the data pages in sequence. It can be used to create input for the dbu util- ity. Note that dbd will skip any NULLs in the key and data fields, thus is unsuitable to convert some peculiar _________________________ [4] The dbd, dba, dbu utilities are quick hacks and are not fit for production use. They were developed late one night, just to test out sdbm, and convert some databases. - 4 - databases that insist in including the terminating null. I have also included a copy of the dbe (ndbm DataBase Editor) by Janick Bergeron [janick@bnr.ca] for your pleas- ure. You may find it more useful than the little dbu util- ity. dbm.[ch] is a dbm library emulation on top of ndbm (and hence suitable for sdbm). Written by Robert Elz. The sdbm library has been around in beta test for quite a long time, and from whatever little feedback I received (maybe no news is good news), I believe it has been func- tioning without any significant problems. I would, of course, appreciate all fixes and/or improvements. Portabil- ity enhancements would especially be useful. Implementation Issues Hash functions: The algorithm behind sdbm implementa- tion needs a good bit-scrambling hash function to be effec- tive. I ran into a set of constants for a simple hash func- tion that seem to help sdbm perform better than ndbm for various inputs: /* * polynomial conversion ignoring overflows * 65599 nice. 65587 even better. */ long dbm_hash(char *str, int len) { register unsigned long n = 0; while (len--) n = n * 65599 + *str++; return n; } There may be better hash functions for the purposes of dynamic hashing. Try your favorite, and check the pagefile. If it contains too many pages with too many holes, (in rela- tion to this one for example) or if sdbm simply stops work- ing (fails after SPLTMAX attempts to split) when you feed your NEWS history file to it, you probably do not have a good hashing function. If you do better (for different types of input), I would like to know about the function you use. Block sizes: It seems (from various tests on a few machines) that a page file block size PBLKSIZ of 1024 is by far the best for performance, but this also happens to limit the size of a key/value pair. Depending on your needs, you may wish to increase the page size, and also adjust PAIRMAX (the maximum size of a key/value pair allowed: should always - 5 - be at least three words smaller than PBLKSIZ.) accordingly. The system-wide version of the library should probably be configured with 1024 (distribution default), as this appears to be sufficient for most common uses of sdbm. Portability This package has been tested in many different UN*Xes even including minix, and appears to be reasonably portable. This does not mean it will port easily to non-UN*X systems. Notes and Miscellaneous The sdbm is not a very complicated package, at least not after you familiarize yourself with the literature on external hashing. There are other interesting algorithms in existence that ensure (approximately) single-read access to a data value associated with any key. These are directory- less schemes such as linear hashing [Lit80] (+ Larson varia- tions), spiral storage [Mar79] or directory schemes such as extensible hashing [Fag79] by Fagin et al. I do hope these sources provide a reasonable playground for experimentation with other algorithms. See the June 1988 issue of ACM Com- puting Surveys [Enb88] for an excellent overview of the field. References [Lar78] P.-A. Larson, "Dynamic Hashing", BIT, vol. 18, pp. 184-201, 1978. [Tho90] Ken Thompson, private communication, Nov. 1990 [Lit80] W. Litwin, "Linear Hashing: A new tool for file and table addressing", Proceedings of the 6th Conference on Very Large Dabatases (Montreal), pp. 212-223, Very Large Database Foundation, Saratoga, Calif., 1980. [Fag79] R. Fagin, J. Nievergelt, N. Pippinger, and H. R. Strong, "Extendible Hashing - A Fast Access Method for Dynamic Files", ACM Trans. Database Syst., vol. 4, no.3, pp. 315-344, Sept. 1979. [Wal84] Rich Wales, "Discussion of 'dbm' data base system", USENET newsgroup unix.wizards, Jan. 1984. [Tor87] Chris Torek, "Re: dbm.a and ndbm.a archives", - 6 - USENET newsgroup comp.unix, 1987. [Mar79] G. N. Martin, "Spiral Storage: Incrementally Augment- able Hash Addressed Storage", Technical Report #27, University of Varwick, Coventry, U.K., 1979. [Enb88] R. J. Enbody and H. C. Du, "Dynamic Hashing Schemes",ACM Computing Surveys, vol. 20, no. 2, pp. 85-113, June 1988. ======================================================================== * ext/SDBM_File/sdbm/readme.ms ======================================================================== .\" tbl | readme.ms | [tn]roff -ms | ... .\" note the "C" (courier) and "CB" fonts: you will probably have to .\" change these. .\" $Id: readme.ms,v 1.1 90/12/13 13:09:15 oz Exp Locker: oz $ .de P1 .br .nr dT 4 .nf .ft C .sp .5 .nr t \\n(dT*\\w'x'u .ta 1u*\\ntu 2u*\\ntu 3u*\\ntu 4u*\\ntu 5u*\\ntu 6u*\\ntu 7u*\\ntu 8u*\\ntu 9u*\\ntu 10u*\\ntu 11u*\\ntu 12u*\\ntu 13u*\\ntu 14u*\\ntu .. .de P2 .br .ft 1 .br .sp .5 .br .fi .. .\" CW uses the typewriter/courier font. .de CW \fC\\$1\\fP\\$2 .. .\" Footnote numbering [by Henry Spencer] .\" \*f for a footnote number.. .\" .FS .\" \*F .\" .FE .\" .ds f \\u\\s-2\\n+f\\s+2\\d .nr f 0 1 .ds F \\n+F. .nr F 0 1 .ND .LP .TL \fIsdbm\fP \(em Substitute DBM .br or .br Berkeley \fIndbm\fP for Every UN*X\** Made Simple .AU Ozan (oz) Yigit .AI The Guild of PD Software Toolmakers Toronto - Canada .sp oz@nexus.yorku.ca .LP .FS UN*X is not a trademark of any (dis)organization. .FE .sp 2 \fIImplementation is the sincerest form of flattery. \(em L. Peter Deutsch\fP .SH A The Clone of the \fIndbm\fP library .PP The sources accompanying this notice \(em \fIsdbm\fP \(em constitute the first public release (Dec. 1990) of a complete clone of the Berkeley UN*X \fIndbm\fP library. The \fIsdbm\fP library is meant to clone the proven functionality of \fIndbm\fP as closely as possible, including a few improvements. It is practical, easy to understand, and compatible. The \fIsdbm\fP library is not derived from any licensed, proprietary or copyrighted software. .PP The \fIsdbm\fP implementation is based on a 1978 algorithm [Lar78] by P.-A. (Paul) Larson known as "Dynamic Hashing". In the course of searching for a substitute for \fIndbm\fP, I prototyped three different external-hashing algorithms [Lar78, Fag79, Lit80] and ultimately chose Larson's algorithm as a basis of the \fIsdbm\fP implementation. The Bell Labs \fIdbm\fP (and therefore \fIndbm\fP) is based on an algorithm invented by Ken Thompson, [Tho90, Tor87] and predates Larson's work. .PP The \fIsdbm\fR programming interface is totally compatible with \fIndbm\fP and includes a slight improvement in database initialization. It is also expected to be binary-compatible under most UN*X versions that support the \fIndbm\fP library. .PP The \fIsdbm\fP implementation shares the shortcomings of the \fIndbm\fP library, as a side effect of various simplifications to the original Larson algorithm. It does produce \fIholes\fP in the page file as it writes pages past the end of file. (Larson's paper include a clever solution to this problem that is a result of using the hash value directly as a block address.) On the other hand, extensive tests seem to indicate that \fIsdbm\fP creates fewer holes in general, and the resulting pagefiles are smaller. The \fIsdbm\fP implementation is also faster than \fIndbm\fP in database creation. Unlike the \fIndbm\fP, the \fIsdbm\fP .CW store operation will not "wander away" trying to split its data pages to insert a datum that \fIcannot\fP (due to elaborate worst-case situations) be inserted. (It will fail after a pre-defined number of attempts.) .SH Important Compatibility Warning .PP The \fIsdbm\fP and \fIndbm\fP libraries \fIcannot\fP share databases: one cannot read the (dir/pag) database created by the other. This is due to the differences between the \fIndbm\fP and \fIsdbm\fP algorithms\**, .FS Torek's discussion [Tor87] indicates that \fIdbm/ndbm\fP implementations use the hash value to traverse the radix trie differently than \fIsdbm\fP and as a result, the page indexes are generated in \fIdifferent\fP order. For more information, send e-mail to the author. .FE and the hash functions used. It is easy to convert between the \fIdbm/ndbm\fP databases and \fIsdbm\fP by ignoring the index completely: see .CW dbd , .CW dbu etc. .R .LP .SH Notice of Intellectual Property .LP \fIThe entire\fP sdbm \fIlibrary package, as authored by me,\fP Ozan S. Yigit, \fIis hereby placed in the public domain.\fP As such, the author is not responsible for the consequences of use of this software, no matter how awful, even if they arise from defects in it. There is no expressed or implied warranty for the \fIsdbm\fP library. .PP Since the \fIsdbm\fP library package is in the public domain, this \fIoriginal\fP release or any additional public-domain releases of the modified original cannot possibly (by definition) be withheld from you. Also by definition, You (singular) have all the rights to this code (including the right to sell without permission, the right to hoard\** .FS You cannot really hoard something that is available to the public at large, but try if it makes you feel any better. .FE and the right to do other icky things as you see fit) but those rights are also granted to everyone else. .PP Please note that all previous distributions of this software contained a copyright (which is now dropped) to protect its origins and its current public domain status against any possible claims and/or challenges. .SH Acknowledgments .PP Many people have been very helpful and supportive. A partial list would necessarily include Rayan Zacherissen (who contributed the man page, and also hacked a MMAP version of \fIsdbm\fP), Arnold Robbins, Chris Lewis, Bill Davidsen, Henry Spencer, Geoff Collyer, Rich Salz (who got me started in the first place), Johannes Ruschein (who did the minix port) and David Tilbrook. I thank you all. .SH Distribution Manifest and Notes .LP This distribution of \fIsdbm\fP includes (at least) the following: .P1 CHANGES change log README this file. biblio a small bibliography on external hashing dba.c a crude (n/s)dbm page file analyzer dbd.c a crude (n/s)dbm page file dumper (for conversion) dbe.1 man page for dbe.c dbe.c Janick's database editor dbm.c a dbm library emulation wrapper for ndbm/sdbm dbm.h header file for the above dbu.c a crude db management utility hash.c hashing function makefile guess. pair.c page-level routines (posted earlier) pair.h header file for the above readme.ms troff source for the README file sdbm.3 man page sdbm.c the real thing sdbm.h header file for the above tune.h place for tuning & portability thingies util.c miscellaneous .P2 .PP .CW dbu is a simple database manipulation program\** that tries to look .FS The .CW dbd , .CW dba , .CW dbu utilities are quick hacks and are not fit for production use. They were developed late one night, just to test out \fIsdbm\fP, and convert some databases. .FE like Bell Labs' .CW cbt utility. It is currently incomplete in functionality. I use .CW dbu to test out the routines: it takes (from stdin) tab separated key/value pairs for commands like .CW build or .CW insert or takes keys for commands like .CW delete or .CW look . .P1 dbu dbmfile .P2 .PP .CW dba is a crude analyzer of \fIdbm/sdbm/ndbm\fP page files. It scans the entire page file, reporting page level statistics, and totals at the end. .PP .CW dbd is a crude dump program for \fIdbm/ndbm/sdbm\fP databases. It ignores the bitmap, and dumps the data pages in sequence. It can be used to create input for the .CW dbu utility. Note that .CW dbd will skip any NULLs in the key and data fields, thus is unsuitable to convert some peculiar databases that insist in including the terminating null. .PP I have also included a copy of the .CW dbe (\fIndbm\fP DataBase Editor) by Janick Bergeron [janick@bnr.ca] for your pleasure. You may find it more useful than the little .CW dbu utility. .PP .CW dbm.[ch] is a \fIdbm\fP library emulation on top of \fIndbm\fP (and hence suitable for \fIsdbm\fP). Written by Robert Elz. .PP The \fIsdbm\fP library has been around in beta test for quite a long time, and from whatever little feedback I received (maybe no news is good news), I believe it has been functioning without any significant problems. I would, of course, appreciate all fixes and/or improvements. Portability enhancements would especially be useful. .SH Implementation Issues .PP Hash functions: The algorithm behind \fIsdbm\fP implementation needs a good bit-scrambling hash function to be effective. I ran into a set of constants for a simple hash function that seem to help \fIsdbm\fP perform better than \fIndbm\fP for various inputs: .P1 /* * polynomial conversion ignoring overflows * 65599 nice. 65587 even better. */ long dbm_hash(char *str, int len) { register unsigned long n = 0; while (len--) n = n * 65599 + *str++; return n; } .P2 .PP There may be better hash functions for the purposes of dynamic hashing. Try your favorite, and check the pagefile. If it contains too many pages with too many holes, (in relation to this one for example) or if \fIsdbm\fP simply stops working (fails after .CW SPLTMAX attempts to split) when you feed your NEWS .CW history file to it, you probably do not have a good hashing function. If you do better (for different types of input), I would like to know about the function you use. .PP Block sizes: It seems (from various tests on a few machines) that a page file block size .CW PBLKSIZ of 1024 is by far the best for performance, but this also happens to limit the size of a key/value pair. Depending on your needs, you may wish to increase the page size, and also adjust .CW PAIRMAX (the maximum size of a key/value pair allowed: should always be at least three words smaller than .CW PBLKSIZ .) accordingly. The system-wide version of the library should probably be configured with 1024 (distribution default), as this appears to be sufficient for most common uses of \fIsdbm\fP. .SH Portability .PP This package has been tested in many different UN*Xes even including minix, and appears to be reasonably portable. This does not mean it will port easily to non-UN*X systems. .SH Notes and Miscellaneous .PP The \fIsdbm\fP is not a very complicated package, at least not after you familiarize yourself with the literature on external hashing. There are other interesting algorithms in existence that ensure (approximately) single-read access to a data value associated with any key. These are directory-less schemes such as \fIlinear hashing\fP [Lit80] (+ Larson variations), \fIspiral storage\fP [Mar79] or directory schemes such as \fIextensible hashing\fP [Fag79] by Fagin et al. I do hope these sources provide a reasonable playground for experimentation with other algorithms. See the June 1988 issue of ACM Computing Surveys [Enb88] for an excellent overview of the field. .PG .SH References .LP .IP [Lar78] 4m P.-A. Larson, "Dynamic Hashing", \fIBIT\fP, vol. 18, pp. 184-201, 1978. .IP [Tho90] 4m Ken Thompson, \fIprivate communication\fP, Nov. 1990 .IP [Lit80] 4m W. Litwin, "Linear Hashing: A new tool for file and table addressing", \fIProceedings of the 6th Conference on Very Large Dabatases (Montreal)\fP, pp. 212-223, Very Large Database Foundation, Saratoga, Calif., 1980. .IP [Fag79] 4m R. Fagin, J. Nievergelt, N. Pippinger, and H. R. Strong, "Extendible Hashing - A Fast Access Method for Dynamic Files", \fIACM Trans. Database Syst.\fP, vol. 4, no.3, pp. 315-344, Sept. 1979. .IP [Wal84] 4m Rich Wales, "Discussion of 'dbm' data base system", \fIUSENET newsgroup unix.wizards\fP, Jan. 1984. .IP [Tor87] 4m Chris Torek, "Re: dbm.a and ndbm.a archives", \fIUSENET newsgroup comp.unix\fP, 1987. .IP [Mar79] 4m G. N. Martin, "Spiral Storage: Incrementally Augmentable Hash Addressed Storage", \fITechnical Report #27\fP, University of Varwick, Coventry, U.K., 1979. .IP [Enb88] 4m R. J. Enbody and H. C. Du, "Dynamic Hashing Schemes",\fIACM Computing Surveys\fP, vol. 20, no. 2, pp. 85-113, June 1988. ======================================================================== * ext/XS-APItest/README ======================================================================== XS::APItest version 0.01 ======================== This module is used to test that the Perl C API is working correctly. It is not meant to be installed. Currently tests that printf formatting works correctly. DEPENDENCIES None. COPYRIGHT AND LICENCE Copyright (C) 2002 Tim Jenness, Christian Soeller and Hugo van der Sanden. All Rights Reserved. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ======================================================================== * ext/XS-Typemap/README ======================================================================== XSTypemap ========= This module tests that the standard XS typemaps are working correctly. perl Makefile.PL make make test Nothing is installed. Currently not all the typemap entries have corresponding tests. Missing entries are T_REF_IV_REF T_PTRDESC T_REFREF T_REFOBJ T_PACKED T_PACKEDARRAY T_DATAUNIT T_CALLBACK T_IN T_INOUT T_OUT Author ------ Tim Jenness Copyright (C) 2001 Tim Jenness All Rights Reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ======================================================================== * lib/unicore/ReadMe.txt ======================================================================== # Date: 2012-01-26, 22:03:00 GMT [KW] # # Unicode Character Database # Copyright (c) 1991-2012 Unicode, Inc. # For terms of use, see http://www.unicode.org/terms_of_use.html # # For documentation, see NamesList.html, # UAX #38, "Unicode Han Database (Unihan)," and # UAX #44, "Unicode Character Database." # This directory contains final data files for the Unicode Character Database (UCD) for Unicode 6.1.0. ======================================================================== * symbian/README ======================================================================== The PerlApp* files are a demonstration application for the CPerlBase class, which is defined and implemented by the PerlBase* files. The rest of the files are part of the Symbian base port. All files are Copyright (c) Nokia, 2004-2005, all rights reserved, and licensed under the same terms as Perl itself. Once the 'sdkinstall' make target has been run in the top level, the PerlApp can be built using the standard Symbian way: bldmake bldfiles abld build wins udeb abld build thumb urel and then packaged into a SIS by: makesis PerlApp.pkg -- ======================================================================== * Copying ======================================================================== GNU GENERAL PUBLIC LICENSE Version 1, February 1989 Copyright (C) 1989 Free Software Foundation, Inc. 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The license agreements of most software companies try to keep users at the mercy of those companies. By contrast, our General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. The General Public License applies to the Free Software Foundation's software and to any other program whose authors commit to using it. You can use it for your programs, too. When we speak of free software, we are referring to freedom, not price. Specifically, the General Public License is designed to make sure that you have the freedom to give away or sell copies of free software, that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it. For example, if you distribute copies of a such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights. We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. The precise terms and conditions for copying, distribution and modification follow. GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License Agreement applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any work containing the Program or a portion of it, either verbatim or with modifications. Each licensee is addressed as "you". 1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this General Public License and to the absence of any warranty; and give any other recipients of the Program a copy of this General Public License along with the Program. You may charge a fee for the physical act of transferring a copy. 2. You may modify your copy or copies of the Program or any portion of it, and copy and distribute such modifications under the terms of Paragraph 1 above, provided that you also do the following: a) cause the modified files to carry prominent notices stating that you changed the files and the date of any change; and b) cause the whole of any work that you distribute or publish, that in whole or in part contains the Program or any part thereof, either with or without modifications, to be licensed at no charge to all third parties under the terms of this General Public License (except that you may choose to grant warranty protection to some or all third parties, at your option). c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the simplest and most usual way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this General Public License. d) You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. Mere aggregation of another independent work with the Program (or its derivative) on a volume of a storage or distribution medium does not bring the other work under the scope of these terms. 3. You may copy and distribute the Program (or a portion or derivative of it, under Paragraph 2) in object code or executable form under the terms of Paragraphs 1 and 2 above provided that you also do one of the following: a) accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Paragraphs 1 and 2 above; or, b) accompany it with a written offer, valid for at least three years, to give any third party free (except for a nominal charge for the cost of distribution) a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Paragraphs 1 and 2 above; or, c) accompany it with the information you received as to where the corresponding source code may be obtained. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form alone.) Source code for a work means the preferred form of the work for making modifications to it. For an executable file, complete source code means all the source code for all modules it contains; but, as a special exception, it need not include source code for modules which are standard libraries that accompany the operating system on which the executable file runs, or for standard header files or definitions files that accompany that operating system. 4. You may not copy, modify, sublicense, distribute or transfer the Program except as expressly provided under this General Public License. Any attempt otherwise to copy, modify, sublicense, distribute or transfer the Program is void, and will automatically terminate your rights to use the Program under this License. However, parties who have received copies, or rights to use copies, from you under this General Public License will not have their licenses terminated so long as such parties remain in full compliance. 5. By copying, distributing or modifying the Program (or any work based on the Program) you indicate your acceptance of this license to do so, and all its terms and conditions. 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. 7. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of the license which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the license, you may choose any version ever published by the Free Software Foundation. 8. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 9. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 10. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS Appendix: How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to humanity, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) 19yy This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301 USA Also add information on how to contact you by electronic and paper mail. If the program is interactive, make it output a short notice like this when it starts in an interactive mode: Gnomovision version 69, Copyright (C) 19xx name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (a program to direct compilers to make passes at assemblers) written by James Hacker. , 1 April 1989 Ty Coon, President of Vice That's all there is to it! ======================================================================== * cpan/Compress-Raw-Bzip2/bzip2-src/LICENSE ======================================================================== -------------------------------------------------------------------------- This program, "bzip2", the associated library "libbzip2", and all documentation, are copyright (C) 1996-2010 Julian R Seward. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required. 3. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software. 4. The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND 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 AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Julian Seward, jseward@bzip.org bzip2/libbzip2 version 1.0.6 of 6 September 2010 -------------------------------------------------------------------------- ======================================================================== * cpan/Locale-Codes/LICENSE ======================================================================== This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. ======================================================================== * cpan/Module-Build/t/properties/license.t ======================================================================== use strict; use lib 't/lib'; use MBTest; use DistGen; plan 'no_plan'; # Ensure any Module::Build modules are loaded from correct directory blib_load('Module::Build'); #--------------------------------------------------------------------------# # Create test distribution #--------------------------------------------------------------------------# { my $dist = DistGen->new( name => 'Simple::Name', version => '0.01', license => 'perl' ); $dist->regen; $dist->chdir_in; my $mb = $dist->new_from_context(); isa_ok( $mb, "Module::Build" ); is( $mb->license, 'perl', "license 'perl' is valid" ); my $meta = $mb->get_metadata( fatal => 0 ); is( $meta->{license} => 'perl', "META license will be 'perl'" ); is( $meta->{resources}{license}, "http://dev.perl.org/licenses/", "META license URL is correct" ); } { my $dist = DistGen->new( name => 'Simple::Name', version => '0.01', license => 'VaporWare' ); $dist->regen; $dist->chdir_in; my $mb = $dist->new_from_context(); isa_ok( $mb, "Module::Build" ); is( $mb->license, 'VaporWare', "license 'VaporWare' is valid" ); my $meta = $mb->get_metadata( fatal => 0 ); is( $meta->{license} => 'unrestricted', "META license will be 'unrestricted'" ); is( $meta->{resources}{license}, "http://example.com/vaporware/", "META license URL is correct" ); } # Test with alpha number # vim:ts=2:sw=2:et:sta:sts=2 ======================================================================== * dist/ExtUtils-CBuilder/LICENSE ======================================================================== This software is copyright (c) 2012 by Ken Williams. This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Terms of the Perl programming language system itself a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" --- The GNU General Public License, Version 1, February 1989 --- This software is Copyright (c) 2012 by Ken Williams. This is free software, licensed under: The GNU General Public License, Version 1, February 1989 GNU GENERAL PUBLIC LICENSE Version 1, February 1989 Copyright (C) 1989 Free Software Foundation, Inc. 51 Franklin St, Suite 500, Boston, MA 02110-1335 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The license agreements of most software companies try to keep users at the mercy of those companies. By contrast, our General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. The General Public License applies to the Free Software Foundation's software and to any other program whose authors commit to using it. You can use it for your programs, too. When we speak of free software, we are referring to freedom, not price. Specifically, the General Public License is designed to make sure that you have the freedom to give away or sell copies of free software, that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it. For example, if you distribute copies of a such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must tell them their rights. We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. The precise terms and conditions for copying, distribution and modification follow. GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License Agreement applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any work containing the Program or a portion of it, either verbatim or with modifications. Each licensee is addressed as "you". 1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this General Public License and to the absence of any warranty; and give any other recipients of the Program a copy of this General Public License along with the Program. You may charge a fee for the physical act of transferring a copy. 2. You may modify your copy or copies of the Program or any portion of it, and copy and distribute such modifications under the terms of Paragraph 1 above, provided that you also do the following: a) cause the modified files to carry prominent notices stating that you changed the files and the date of any change; and b) cause the whole of any work that you distribute or publish, that in whole or in part contains the Program or any part thereof, either with or without modifications, to be licensed at no charge to all third parties under the terms of this General Public License (except that you may choose to grant warranty protection to some or all third parties, at your option). c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the simplest and most usual way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this General Public License. d) You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. Mere aggregation of another independent work with the Program (or its derivative) on a volume of a storage or distribution medium does not bring the other work under the scope of these terms. 3. You may copy and distribute the Program (or a portion or derivative of it, under Paragraph 2) in object code or executable form under the terms of Paragraphs 1 and 2 above provided that you also do one of the following: a) accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Paragraphs 1 and 2 above; or, b) accompany it with a written offer, valid for at least three years, to give any third party free (except for a nominal charge for the cost of distribution) a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Paragraphs 1 and 2 above; or, c) accompany it with the information you received as to where the corresponding source code may be obtained. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form alone.) Source code for a work means the preferred form of the work for making modifications to it. For an executable file, complete source code means all the source code for all modules it contains; but, as a special exception, it need not include source code for modules which are standard libraries that accompany the operating system on which the executable file runs, or for standard header files or definitions files that accompany that operating system. 4. You may not copy, modify, sublicense, distribute or transfer the Program except as expressly provided under this General Public License. Any attempt otherwise to copy, modify, sublicense, distribute or transfer the Program is void, and will automatically terminate your rights to use the Program under this License. However, parties who have received copies, or rights to use copies, from you under this General Public License will not have their licenses terminated so long as such parties remain in full compliance. 5. By copying, distributing or modifying the Program (or any work based on the Program) you indicate your acceptance of this license to do so, and all its terms and conditions. 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. 7. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of the license which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of the license, you may choose any version ever published by the Free Software Foundation. 8. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 9. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 10. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS Appendix: How to Apply These Terms to Your New Programs If you develop a new program, and you want it to be of the greatest possible use to humanity, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the "copyright" line and a pointer to where the full notice is found. Copyright (C) 19yy This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301 USA Also add information on how to contact you by electronic and paper mail. If the program is interactive, make it output a short notice like this when it starts in an interactive mode: Gnomovision version 69, Copyright (C) 19xx name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details. The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program. You should also get your employer (if you work as a programmer) or your school, if any, to sign a "copyright disclaimer" for the program, if necessary. Here a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (a program to direct compilers to make passes at assemblers) written by James Hacker. , 1 April 1989 Ty Coon, President of Vice That's all there is to it! --- The Artistic License 1.0 --- This software is Copyright (c) 2012 by Ken Williams. This is free software, licensed under: The Artistic License 1.0 The Artistic License Preamble The intent of this document is to state the conditions under which a Package may be copied, such that the Copyright Holder maintains some semblance of artistic control over the development of the package, while giving the users of the package the right to use and distribute the Package in a more-or-less customary fashion, plus the right to make reasonable modifications. Definitions: - "Package" refers to the collection of files distributed by the Copyright Holder, and derivatives of that collection of files created through textual modification. - "Standard Version" refers to such a Package if it has not been modified, or has been modified in accordance with the wishes of the Copyright Holder. - "Copyright Holder" is whoever is named in the copyright or copyrights for the package. - "You" is you, if you're thinking about copying or distributing this Package. - "Reasonable copying fee" is whatever you can justify on the basis of media cost, duplication charges, time of people involved, and so on. (You will not be required to justify it to the Copyright Holder, but only to the computing community at large as a market that must bear the fee.) - "Freely Available" means that no fee is charged for the item itself, though there may be fees involved in handling the item. It also means that recipients of the item may redistribute it under the same conditions they received it. 1. You may make and give away verbatim copies of the source form of the Standard Version of this Package without restriction, provided that you duplicate all of the original copyright notices and associated disclaimers. 2. You may apply bug fixes, portability fixes and other modifications derived from the Public Domain or from the Copyright Holder. A Package modified in such a way shall still be considered the Standard Version. 3. You may otherwise modify your copy of this Package in any way, provided that you insert a prominent notice in each changed file stating how and when you changed that file, and provided that you do at least ONE of the following: a) place your modifications in the Public Domain or otherwise make them Freely Available, such as by posting said modifications to Usenet or an equivalent medium, or placing the modifications on a major archive site such as ftp.uu.net, or by allowing the Copyright Holder to include your modifications in the Standard Version of the Package. b) use the modified Package only within your corporation or organization. c) rename any non-standard executables so the names do not conflict with standard executables, which must also be provided, and provide a separate manual page for each non-standard executable that clearly documents how it differs from the Standard Version. d) make other distribution arrangements with the Copyright Holder. 4. You may distribute the programs of this Package in object code or executable form, provided that you do at least ONE of the following: a) distribute a Standard Version of the executables and library files, together with instructions (in the manual page or equivalent) on where to get the Standard Version. b) accompany the distribution with the machine-readable source of the Package with your modifications. c) accompany any non-standard executables with their corresponding Standard Version executables, giving the non-standard executables non-standard names, and clearly documenting the differences in manual pages (or equivalent), together with instructions on where to get the Standard Version. d) make other distribution arrangements with the Copyright Holder. 5. You may charge a reasonable copying fee for any distribution of this Package. You may charge any fee you choose for support of this Package. You may not charge a fee for this Package itself. However, you may distribute this Package in aggregate with other (possibly commercial) programs as part of a larger (possibly commercial) software distribution provided that you do not advertise this Package as a product of your own. 6. The scripts and library files supplied as input to or produced as output from the programs of this Package do not automatically fall under the copyright of this Package, but belong to whomever generated them, and may be sold commercially, and may be aggregated with this Package. 7. C or perl subroutines supplied by you and linked into this Package shall not be considered part of this Package. 8. The name of the Copyright Holder may not be used to endorse or promote products derived from this software without specific prior written permission. 9. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. The End