This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: biostart, Next: bitflags, Prev: biodesign, Up: Module List Getting Started *************** NAME ==== Bioperl - Getting Started SYNOPSIS ======== #!/usr/local/bin/perl use Bio::Seq; use Bio::SeqIO; $seqin = Bio::SeqIO->new( '-format' => 'EMBL' , -file => 'myfile.dat'); $seqout= Bio::SeqIO->new( '-format' => 'Fasta', -file => '>output.fa'); while((my $seqobj = $seqin->next_seq())) { print "Seen sequence ",$seqobj->display_id,", start of seq ", substr($seqobj->seq,1,10),"\n"; if( $seqobj->moltype eq 'dna') { $rev = $seqobj->revcom; $id = $seqobj->display_id(); $id = "$id.rev"; $rev->display_id($id); $seqout->write_seq($rev); } foreach $feat ( $seqobj->top_SeqFeatures() ) { if( $feat->primary_tag eq 'exon' ) { print STDOUT "Location ",$feat->start,":", $feat->end," GFF[",$feat->gff_string,"]\n"; } } } DESCRIPTION =========== Bioperl is a set of Perl modules that represent useful biological objects. Some of the key objects include: Sequences, features on sequences, databases of sequences, flat file representations of sequences and similarity search results. Because bioperl is formed from Perl modules, there are no actual useable programs in the distribution (this is not actually true. In the scripts directory there are a few useful programs. But not a great deal...). You have to write the programs which use bioperl. It is very easy to write programs using the bioperl modules, as alot of the complex processing happens in the modules and not in the part of the program which you have to write. The idea is that you can connet up a number of the modules to do useful things. The synopsis above gives a simple script which uses bioperl. Stepping through this script, the lines mean the following things: The first line indicates that in a UNIX manner, the /usr/local/bin/perl executable is used to execute this script. Bioperl is not a new version of perl, it just extends the standard perl for biological objects #!/usr/local/bin/perl These use lines actually import the bioperl modules. Bio::Seq is the bioperl main sequence object; Bio::SeqIO is the bioperl support for sequence input/output into files use Bio::Seq; use Bio::SeqIO; These two lines create two SeqIO streams: one for reading in sequences and one for outputting sequences. Using the '-argument' => value syntax is common in bioperl. The file argument is like an argument to open() (notice that in the seqout case there is a greater-than sign, indicating opening the file for writing). You can also pass in filehandles or FileHandle objects by using the -fh argument, see SeqIO documentation for details. Many formarts in bioperl are handled, including Fasta, EMBL. GenBank, Swissprot (swiss), PIR and GCG. $seqin = Bio::SeqIO->new( '-format' => 'EMBL' , -file => 'myfile.dat'); $seqout= Bio::SeqIO->new( '-format' => 'Fasta', -file => '>output.fa'); This is the main loop which will loop progressively through sequences in a file. Each call to seqio->next_seq() provides a new sequence object from the file, reading successively. while((my $seqobj = $seqio->next_seq())) { This print line access fields in the sequence object directly. The seqobj->display_id is the way to access the display_id attribute of the sequence object. The seqobj->seq method gets the actual sequence out as string. Then you can do manipulation of this if you want to (there are however easy ways of doing truncation, reverse-complement and translation). print "Seen sequence ",$seqobj->display_id,", start of seq ", substr($seqobj->seq,1,10),"\n"; Bioperl has to guess the type of the sequence, being either dna, rna or protein. The moltype attribute gives one of these three possibilities if( $seqobj->moltype eq 'dna') { The seqobj->revcom method provides the reverse complement of the seqobj object as another sequence object. The $rev variable therefore is another sequence object. For example, one could repeat the above print line for this sequence object (putting rev in place of seqobj). In this case we are going to output the object into the file stream we built earlier on. $rev = $seqobj->revcom; When we output it, we want the id of the outputted object to be changed to "$id.rev", ie, with .rev on the end of the name. The following lines retrieve the id of the sequence object, add .rev to this and then set the display_id of the rev sequence object to this. Notice that to set the display_id attribute you just need call the same method (display_id) with the new value as an argument. $id = $seqobj->display_id(); $id = "$id.rev"; $rev->display_id($id); The write_seq method on the seqout output object writes the $rev object to the filestream we built at the top of the script. The filestream knows that it is outputting in fasta format, and so it provides fasta output $seqout->write_seq($rev); } This final loop loops over sequence features in the sequence object, trying to find ones who have been tagged as 'exon'. Features have start and end attributes and can be outputted in GFF format, a standarised format for sequence features foreach $feat ( $seqobj->top_SeqFeatures() ) { if( $feat->primary_tag eq 'exon' ) { print STDOUT "Location ",$feat->start,":", $feat->end," GFF[",$feat->gff_string,"]\n"; } } } Short Description of Objects. ============================= Here is a very quick overview of the objects in bioperl Bio::Seq - sequence object # the following methods return strings $seqobj->display_id(); # the human read-able id of the sequence $seqobj->seq(); # string of sequence $seqobj->subseq(5,10); # part of the sequence as a string $seqobj->accession_number(); # when there, the accession number $seqobj->moltype(); # one of 'dna','rna','protein' $seqobj->primary_id(); # a unique id for this sequence irregardless # of its display_id or accession number # the following methods return an array of # Bio::SeqFeature objects $seqobj->top_SeqFeatures # The 'top level' sequence features $seqobj->all_SeqFeatures # All sequence features, including sub # seq features # the following methods returns new sequence objects, but # do not transfer features across $seqobj->trunc(5,10) # truncation from 5 to 10 as new object $seqobj->revcom # reverse complements sequence $seqobj->translate # translation of the sequence Bio::SeqFeature objects: # attributes which return numbers $feat->start # start position (1 is the first base) $feat->end # end position (2 is the second base) $feat->strand # 1 means forward, -1 reverse, 0 not relevant # attributes which return strings $feat->primary_tag # the main 'name' of the sequence feature, # eg, 'exon' $feat->source_tag # where the feature comes from, eg, 'EMBL_GenBank', # or 'BLAST' # attributes which return sequences (these are the more restrictive # Bio::PrimarySeq objects, not Bio::Seq objects. The main difference # is that these objects do not themselves contain sequence features) $feat->seq # the sequence between start,end on the # correct strand of the sequence $feat->entire_seq # the entire sequence, not necessarily on the # correct strand # useful methods for feature comparisons, for start/end points $feat->overlap($other) # does feat and other overlap? $feat->contains($other) # is other completely within feat? $feat->equals($other) # does feat and other completely agree? # sub features. For complex join() statements, the features # is one sequence feature with many sub SeqFeatures $feat->sub_SeqFeatures # array of sub seq features BLAST ===== ...stuff on running BLAST and parsing results... Database Access =============== Feel free to add to this document.  File: pm.info, Node: bitflags, Next: blib, Prev: biostart, Up: Module List Perl module for generating bit flags ************************************ NAME ==== bitflags - Perl module for generating bit flags SYNOPSIS ======== use bitflags qw( ALPHA BETA GAMMA DELTA ); use bitflags qw( EPSILON ZETA ETA THETA ); use bitflags qw( :start=2 BEE CEE DEE EEE EFF GEE ); use bitflags qw( :start=^3 EIGHT SIXTEEN THIRTY_TWO ); DESCRIPTION =========== The `bitflags' module allows you to form a set of unique bit flags, for ORing together. Think of the `O_' constants you get from Fcntl... that's the idea. Successive calls remember the previous power used, so you don't have to set a starting number, or declare all the constants on one line. If you do want to set a starting value, use the `:start' flag as the first argument in the import list. If the flag is `:start=NNN', where `NNN' is some positive integer, that value is checked to ensure it's a power of two, and that value is used as the starting value. If it is not a power of two, the program will croak. If the flag is `:start=^NNN', where `NNN' is some positive integer, that value is the power of two to start with. Implementation -------------- The flags are created as `()'-prototyped functions in the caller's package, not unlike the constant pragma. AUTHOR ====== Jeff "`japhy'" Pinyan. URL: `http://www.pobox.com/~japhy/' Email: `japhy@pobox.com', `PINYAN@cpan.org' CPAN ID: `PINYAN' Online at: `japhy' on `#perl' on DALnet and EFnet. `japhy' at `http://www.perlguru.com/'. `japhy' at `http://www.perlmonks.org/'. "Coding With Style" column at `http://www.perlmonth.com/'.  File: pm.info, Node: blib, Next: build, Prev: bitflags, Up: Module List Use MakeMaker's uninstalled version of a package ************************************************ NAME ==== blib - Use MakeMaker's uninstalled version of a package SYNOPSIS ======== perl -Mblib script [args...] perl -Mblib=dir script [args...] DESCRIPTION =========== Looks for MakeMaker-like *'blib'* directory structure starting in dir (or current directory) and working back up to five levels of '..'. Intended for use on command line with -M option as a way of testing arbitary scripts against an uninstalled version of a package. However it is possible to : use blib; or use blib '..'; etc. if you really must. BUGS ==== Pollutes global name space for development only task. AUTHOR ====== Nick Ing-Simmons nik@tiuk.ti.com  File: pm.info, Node: build, Next: bytes, Prev: blib, Up: Module List the equivalent of "make" of "Build'n'Play" (BnP) ************************************************ NAME ==== build - the equivalent of "make" of "Build'n'Play" (BnP) SYNOPSIS ======== build [-g] - use "genopt" installation method [-n] - use "normal" installation method [-p ] - the absolute prefix of the installation hierarchy [-r ] - optional relative path ("category") for target [-s ] - add search path(s) for local source directory(ies) [-u ] - add URL(s) for remote source directory(ies) - the command or software package to install (clean, bnp, perl, tools, sfio, gimp, imagick, ...) build [-h] - print help screen and exit build -v - print version information and exit DESCRIPTION =========== Think of "Build'n'Play" as something very similar to "make" and "Makefiles": There is a command called "build" (the equivalent of "make") and several "Buildfiles" (called "perl.bnp", "gimp.bnp" and so on) for the different "targets" you can "build". Just say "build perl" for building and installing Perl and its modules, for instance. Just like "make", which doesn't re-create the files that are "up to date" when you invoke "make" more than once, the "build" command does not re-execute the commands that have already been executed successfully in the previous call of "build". This automatic recovery mechanism is the central idea behind "Build'n'Play": If something goes wrong during the installation (for instance, if a compiler error occurs), or if you abort it with "`Ctrl-C'", you can simply re-run "build" (after you resolved the problem in question) with the same options (important!) and "Build'n'Play" will automatically continue the installation where it left off (thereby attempting to re-execute the command which failed previously or which was interrupted). There is also a command "build clean" (the equivalent of "make clean") for deleting the internal temporary workspace, which should always be used between different builds (but not when restarting an aborted installation, of course!). For a complete list of available targets you can build, just call "build" without parameters: % ./build Note that it is possible to install subsets of a given target if such subsets have been defined in the corresponding "Buildfile" (".bnp"). To do so, just append the name(s) of the desired subset(s) (or "subtarget(s)") to the name of the (main) target using dots ("."), as in the following example: % ./build perl.core.fox (Note that the order of the subtargets after the main target does not matter.) This will install Perl itself ("core") plus those modules ("fox") which are discussed more thoroughly in the book "Programmieren mit Perl-Modulen" (by O'Reilly Verlag Koeln, 1999) accompanying the CD-ROM on which "Build'n'Play" was first published (the fox is the animal on the cover of that book). If you want to know which subtargets are available, use the tool "tags" from the "misc" subdirectory in the "Build'n'Play" distribution, e.g. % ./misc/tags perl When working with "build", two files will be especially important for you (unless the installation succeeds without any errors, which it is unlikely to do when you run it for the first time): The installation script (or "Buildfile") ".bnp" and the automatic recovery file "recover.bnp". Both files are located in the directory "/lib/BnP/lib/" (when using the "normal" installation method) or "/lib/BnP/" (when using the "genopt" installation method), where "" is the installation prefix such as "/usr/local", "/opt" or the like, as specified via the "-p" option, and "" is the name of the software package to be installed. (For a discussion of the two installation methods and their corresponding command line options, as well as the "-p" option, see the section "OPTIONS" below.) If the "build" command is run from the original distribution's directory or from the CD-ROM, the file ".bnp" is automatically copied from that directory to the directory mentioned above, as soon as an error occurs during the installation (but not if you interrupt it manually using "Ctrl-C"). After that this copy takes precedence over its original in the distribution directory or on the CD-ROM, i.e., the "build" command will execute this copy rather than the original file when invoked again subsequently with the same "". (If you don't want that, simply delete this copy.) This is done because you will most likely need to change this file after an error occurred, and you obviously can't do that on a CD-ROM, and you probably don't want to do that in the original distribution. (If you don't want this to happen and if you actually want to edit the file in the original distribution, simply delete the file ".cdrom" from the distribution directory BEFORE using the "build" command.) When you make any changes to that copy of the installation script, you may also need to change the corresponding commands in the automatic recovery file (this file is used by the automatic recovery mechanism (see `BnP(3)' in this node for more details) in order to determine which commands have already been executed successfully and which are hence to be skipped in any later runs). You may also want to use this automatic recovery file for looking up which was the last command in your installation script that was successfully executed. In addition to these two files, you may want to check the temporary internal workspace (in "/lib/BnP/tmp/" or "/pkg/BnP/tmp/") where the software packages are unpacked and compiled, in order to find out what went wrong (in case of an error) and how to fix it. OPTIONS ======= Note that option letters cannot be condensed into a single option letter string in this script, i.e., an option string such as "-gp/opt" would be illegal and result in an error message. Note however that whitespace between the option letter and its argument (if it takes one) is optional. If the (mutually exclusive) options "-g" and "-n" are both specified, the last one overrides all previous ones, unless the option "-r" is used, in which case the "-g" option is implicitly assumed, regardless of wether any "-g" or "-n" option has been specified or not. -g This option enables the "genopt" installation method. Use this option if you don't want to have your software packages installed all into the same directory (such as "/usr/local/bin"), trampling over one another and making the de-installation almost impossible (except for trivial cases), but each into a separate directory subtree of their own. See `genopt(1)' in this node for more details. (Note that you can still use the prefix "/usr/local" in combination with this installation method, but this is actually not recommended, because possible name conflicts can be resolved much more easily (automatically, through a command line option) if a completely new installation directory tree is used, such as "/opt" or "/sw" or whatever you choose.) -n This option enables the "normal" or standard Unix installation method, in which software packages are all installed into the same installation directories (such as "/usr/local/bin", "/usr/local/man" and so on). Note that you can use any installation prefix you want in combination with this installation method; you are not limited to using "/usr/local". You will usually not need this option, though, because this is the default setting. However, if you set the default to the "genopt" installation method (by changing the corresponding configuration constant in the script "build"), you can use this option to temporarily disable the "genopt" installation method and to revert the behaviour to the usual Unix installation method. `-p ' Use this option to specify the installation prefix to be used. The default is "/usr/local", in case you don't specify any prefix explicitly. `-r ' This option can be used in combination with the "genopt" installation method in order to specify a subdirectory path (a "category") relative to the physical software packages installation directory subtree, usually "/packages" (e.g. "/opt/packages"). This allows you to group related software packages into categories and subcategories (i.e., subdirectories and subsubdirectories) of your own choosing (as many levels deep as you wish). Note that using this option automatically implies the "genopt" installation method, i.e., this option is automatically treated as though the option "-g" had been specified as well (this also overrides any "-n" option which may have been specified). `-s ' Use this option for specifying any additional directories containing source distribution files which are relevant to your installation. You may use this option multiple times on the same command line in order to add more than one directory. You may also concatenate several directories using colons (":"), e.g. -s dir1:dir2:dir3 You may also combine these two forms, e.g. -s d1:d2:d3 -s d4:d5 Use this option to indicate the path to your CD-ROM drive (e.g. "`-s /cd'") if this path is NOT "/cdrom" or "/cdrec" AND if you are not starting the "build" command from the "BnP" directory on the CD-ROM (in which case "build" already knows (implicitly) about the path to your CD-ROM drive). You can also use this option to indicate the path to a mirror of a software archive (such as "CPAN", for example) on your hard disk, e.g. "`-s /pub/mirrors/CPAN'", in order to avoid desnecessary downloads. Files not found on your local file system (i.e., all the default directories already configured into the "build" command plus any additional source directories you may have specified with this option) will continue to be downloaded automatically, though. Note that the directory paths given should not end in a slash ("/"). Note also that you do not need to specify the "generic" subdirectories "CPAN", "BnP/src", "BnP" and "src", i.e., you may (and should) specify "`-s /cd'" instead of "`-s /cd/CPAN:/cd/BnP:/cd/BnP/src'" and "`-s /pub/mirrors'" instead of "`-s /pub/mirrors/CPAN'", for instance. Finally, note that the directories you specify will be searched in the given order (from left to right). `-u ' Use this option for specifying any additional (or alternative) URLs needed for downloading source distribution files which are relevant to your installation. You may use this option multiple times on the same command line in order to add more than one URL. You may also concatenate several URLs using whitespace - but don't forget to enclose the whole argument in (single or double) quotes in this case: -u 'ftp://ftp.engelschall.com/pub/bnp ftp://ftp.netsw.org/netsw' You may also combine these two forms, e.g. you may also write -u 'url1 url2 url3' -u 'url4 url5' This option is especially useful if you have a server on your local network with a mirror of some software archive you need, e.g. -u ftp://instserv.yourdomain.com/pub/mirrors/CPAN Note that the given URLs should always end in the name of a directory, but they should nevertheless not end in a slash ("/"). Note also that (in contrast to the "-s" option described above) you DO need to specify the "CPAN" directory in the URLs of "CPAN" mirror servers (unless the server doesn't use that name, then use its equivalent instead), e.g. -u ftp://ftp.cdrom.com/pub/perl/CPAN -u ftp://ftp.metronet.com/pub/perl However, do NOT specify any subdirectory BELOW the "CPAN" directory level (or its equivalent on that host). For servers other than "CPAN" mirror servers you will usually specify the URL up to the directory containing the file of interest, unless you need more than one file from the same server but from different directories, in which case you should specify the path common to all files in the URL and the differing paths to the different subdirectories in the "RELPATH" argument of the corresponding "fetch()" method call in your installation script (see `BnP(3)' in this node for more details). Finally, note that the URLs you specify will be tried in the given order (from left to right). -h If this option is found among the options to the "build" command, the internal processing of command line options is terminated immediately, a help screen is printed to STDOUT and the program stops (with exit code "1"). Note that this option is optional in the sense that calling the "build" command without any parameters produces exactly the same result. -v If this option is found among the options to the "build" command, the internal processing of command line options is terminated immediately, the name and current version number of the "build" command is printed to STDOUT and the program stops (with exit code "1"). FILES ===== build - the equivalent of "make" of "Build'n'Play" genopt - a tool for maintaining a software package installation hierarchy which allows complete de-installation (without residues whatsoever) using a symbolic link access layer BnP.pm - the library which provides the automatic recovery mechanism which allows you to simply re-run the "build" command after an error occurred during the installation; the installation will auto- matically resume where it left off miniperl - a "stripped down" version of the Perl interpreter provided in the original Perl distribution, which is used here for bootstrapping Perl in case no Perl 5 is installed yet on your system .bnp - the "Buildfile" (in analogy to "Makefile") or installation script for the installation target recover.bnp - the command log file needed for the automatic recovery of the installation process recover.000 - safeguarded copies of the "recover.bnp" file recover.001 of previous installation runs (you might need ... to re-use one of these!) DIRECTORIES =========== On the CD-ROM from O'Reilly Verlag ("Programmieren mit Perl-Modulen"): /cdrom/CPAN/ - contains the CPAN snapshot /cdrom/BnP/ - contains the BnP distribution /cdrom/BnP/misc/ - contains miscellaneous tools /cdrom/BnP/src/ - contains other source files (The latter directory contains source files not found in CPAN (anymore), as well as tools like "bzip2", "snarf", GNU "make" and "patch".) When using the "normal" installation method with a prefix such as "`/usr/local'": /usr/local/lib/BnP/arc/ - contains all BnP files /usr/local/bin/ - contains build and genopt /usr/local/lib/BnP/lib/ - contains BnP.pm and miniperl /usr/local/lib/BnP/lib/perl/ - contains perl.bnp and recover.* files /usr/local/lib/BnP/lib/perl/src/ - contains source files /usr/local/lib/BnP/lib// - contains .bnp and recover.* files /usr/local/lib/BnP/lib//src/ - contains source files /usr/local/man/... - contains BnP's manpages /usr/local/lib/BnP/tmp/ - contains internal workspace When using the "genopt" installation method with a prefix such as "`/opt'": /opt/pkg/BnP/arc/ - contains all BnP files /opt/pkg/BnP/bin/ - contains build and genopt /opt/lib/BnP/ - contains BnP.pm and miniperl /opt/lib/BnP/perl/ - contains perl.bnp and recover.* files /opt/lib/BnP/perl/src/ - contains source files /opt/lib/BnP// - contains .bnp and recover.* files /opt/lib/BnP//src/ - contains source files /opt/pkg/BnP/man/... - contains BnP's manpages /opt/pkg/BnP/tmp/ - contains internal workspace Note that "`/opt/lib/BnP/'" is exactly the same directory as "`/opt/pkg/BnP/lib/'", but via a different symbolic link. DIAGNOSTICS =========== * `"Can't find the indispensable tool ''!"' One of the absolutely indispensable Unix tools (like sh, gunzip, tar etc.) could not be found in the search path (as given by the "$PATH" environment variable). This occurs if the "$PATH" environment variable is not set properly or if your Unix installation is seriously incomplete or broken. Check your "$PATH" environment variable to see wether it includes all necessary paths, or install the missing tool. * `"Can't find '' in ''!"' * `"Can't find '' neither in ''' `nor in ''' `using offsets ''!"' * `"Can't find '' neither in ''' `nor in ''' `using offsets '' and ''!"' Neither the expected directory(ies) nor your current search path (i.e., the directories listed in your environment variable "`$PATH'") contain the requested file "", not even in certain default subdirectories of these directories. Your search path "`$PATH'" may need to be adjusted, or you may need to specify the path to your CD-ROM drive using the command line option "-s" (see also the section "OPTIONS" above). Maybe you didn't start the "build" command from the CD-ROM or the original distribution. If in doubt, "cd" to the "BnP" directory on your CD-ROM (e.g. "cd /cdrom/BnP") or into the directory of the original distribution and start the "build" command from there, i.e., with "./build". * `"Can't find any tool (snarf, lynx) for downloading!"' You probably forgot to mount your CD-ROM drive. May also be caused by starting copies of "build" from different places. If in doubt, cd to the "BnP" directory on the CD-ROM or the original distribution directory and use "./build" instead of "build". Moreover, you do not seem to have either "snarf" or "lynx" installed. You might want to install one of these (or change the configuration in "BnP.pm" for another tool) in order for automatic downloads to work in the future, which will benefit you as soon as you will attempt to install a module newer than the CPAN snapshot included on the CD-ROM. (Note that you can install "snarf" with "Build'n'Play" itself via the command "build tools.snarf". If you don't have "Build'n'Play" on a CD-ROM, you may need to create a subdirectory named "src" in your original distribution directory first and then to manually download the file "snarf-1.6.1b.tar.gz" from the URL "ftp://ftp.engelschall.com/pub/bnp/packages/" into that subdirectory before actually doing so.) * `"Download of '' with '' failed!"' The program was unable to load the mentioned file from any of the URLs specified by you on the command line or configured in ".bnp". This means that either there was no connection, or the file was not found on any of the specified or configured servers. Try again later or try a different URL if everything else seems to be correct. Note that this error message can also occur when you forget to mount your CD-ROM drive, in case you have one of the configured download tools (currently "snarf" and "lynx") installed on your system but no working network access. * `"Can't install the "Build'n'Play" (BnP) package;' `please re-run this command ('build bnp')' `from the CD-ROM or the original distribution!"' Be sure to start "build" from the CD-ROM or the original distribution. If in doubt, "cd" to the "BnP" directory on your CD-ROM (e.g. "cd /cdrom/BnP") or into the directory of the original distribution and start the "build" command from there, i.e., with "./build". * `" in patch command!"' An error (more closely described by "") occurred in one of the Perl expressions given as arguments to the "patch()" method in "BnP.pm". This is usually a Perl syntax error. Check your ".bnp" installation script. Watch out for proper quoting and escaping! * `"Next command deviates from the automatic recovery file -' `discarding the remainder of the automatic recovery file!"' This warning message appears whenever you apply changes to the ".bnp" installation script (after an error with program abortion) which cause the installation to take a different course than in previous runs. This happens for instance if you comment out some part in the installation script, if you insert new commands or if you alter existing ones. This warning message might show that the installation is not doing what you intended. In such a case you can always abort with "Ctrl-C", make the necessary changes, and re-run "build". Note that you can always go back to the recovery files of all previous installation attempts, which are kept for exactly this purpose (with ascending numbers in their filename extensions, i.e., "recover.000" is the recovery file from the first installation attempt, "recover.001" from the second, and so on). All other error messages indicate that something is wrong either with your command line parameters (and the corresponding error message should help you to correct the problem), or with the installation (compiler errors and the like - again, the corresponding error message should help you to fix this problem), or with your system (most probably a problem with file permissions in your file system, or a disk capacity overrun). SEE ALSO ======== genopt(1), BnP(3), make(1), CPAN(3). VERSION ======= This man page documents "build" version 2.1.0. AUTHOR ====== Steffen Beyer sb@engelschall.com www.engelschall.com/u/sb/download/ COPYRIGHT ========= Copyright (c) 1998 by Steffen Beyer. All rights reserved. LICENSE ======= This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself, i.e., under the terms of the "Artistic License" or the "GNU General Public License". Please refer to the files "Artistic.txt" and "GNU_GPL.txt" in this distribution for details! DISCLAIMER ========== This package 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.  File: pm.info, Node: bytes, Next: charnames, Prev: build, Up: Module List Perl pragma to force byte semantics rather than character semantics ******************************************************************* NAME ==== bytes - Perl pragma to force byte semantics rather than character semantics SYNOPSIS ======== use bytes; no bytes; DESCRIPTION =========== WARNING: The implementation of Unicode support in Perl is incomplete. See *Note Perlunicode: (perl.info)perlunicode, for the exact details. The `use bytes' pragma disables character semantics for the rest of the lexical scope in which it appears. `no bytes' can be used to reverse the effect of `use bytes' within the current lexical scope. Perl normally assumes character semantics in the presence of character data (i.e. data that has come from a source that has been marked as being of a particular character encoding). To understand the implications and differences between character semantics and byte semantics, see *Note Perlunicode: (perl.info)perlunicode,. SEE ALSO ======== *Note Perlunicode: (perl.info)perlunicode,, *Note Utf8: utf8,  File: pm.info, Node: charnames, Next: constant, Prev: bytes, Up: Module List define character names for `\N{named}' string literal escape. ************************************************************* NAME ==== charnames - define character names for `\N{named}' string literal escape. SYNOPSIS ======== use charnames ':full'; print "\N{GREEK SMALL LETTER SIGMA} is called sigma.\n"; use charnames ':short'; print "\N{greek:Sigma} is an upper-case sigma.\n"; use charnames qw(cyrillic greek); print "\N{sigma} is Greek sigma, and \N{be} is Cyrillic b.\n"; DESCRIPTION =========== Pragma `use charnames' supports arguments `:full', `:short' and script names. If `:full' is present, for expansion of `\N{CHARNAME}}' string `CHARNAME' is first looked in the list of standard Unicode names of chars. If `:short' is present, and `CHARNAME' has the form `SCRIPT:CNAME', then CNAME is looked up as a letter in script `SCRIPT'. If pragma `use charnames' is used with script name arguments, then for `\N{CHARNAME}}' the name `CHARNAME' is looked up as a letter in the given scripts (in the specified order). For lookup of `CHARNAME' inside a given script `SCRIPTNAME' this pragma looks for the names SCRIPTNAME CAPITAL LETTER CHARNAME SCRIPTNAME SMALL LETTER CHARNAME SCRIPTNAME LETTER CHARNAME in the table of standard Unicode names. If `CHARNAME' is lowercase, then the `CAPITAL' variant is ignored, otherwise the `SMALL' variant is ignored. CUSTOM TRANSLATORS ================== The mechanism of translation of `\N{...}' escapes is general and not hardwired into `charnames.pm'. A module can install custom translations (inside the scope which uses the module) with the following magic incantation: use charnames (); # for $charnames::hint_bits sub import { shift; $^H |= $charnames::hint_bits; $^H{charnames} = \&translator; } Here translator() is a subroutine which takes `CHARNAME' as an argument, and returns text to insert into the string instead of the `\N{CHARNAME}' escape. Since the text to insert should be different in bytes mode and out of it, the function should check the current state of bytes-flag as in: use bytes (); # for $bytes::hint_bits sub translator { if ($^H & $bytes::hint_bits) { return bytes_translator(@_); } else { return utf8_translator(@_); } } BUGS ==== Since evaluation of the translation function happens in a middle of compilation (of a string literal), the translation function should not do any evals or requires. This restriction should be lifted in a future version of Perl.  File: pm.info, Node: constant, Next: cyrillic, Prev: charnames, Up: Module List Perl pragma to declare constants ******************************** NAME ==== constant - Perl pragma to declare constants SYNOPSIS ======== use constant BUFFER_SIZE => 4096; use constant ONE_YEAR => 365.2425 * 24 * 60 * 60; use constant PI => 4 * atan2 1, 1; use constant DEBUGGING => 0; use constant ORACLE => 'oracle@cs.indiana.edu'; use constant USERNAME => scalar getpwuid($<); use constant USERINFO => getpwuid($<); sub deg2rad { PI * $_[0] / 180 } print "This line does nothing" unless DEBUGGING; # references can be constants use constant CHASH => { foo => 42 }; use constant CARRAY => [ 1,2,3,4 ]; use constant CPSEUDOHASH => [ { foo => 1}, 42 ]; use constant CCODE => sub { "bite $_[0]\n" }; print CHASH->{foo}; print CARRAY->[$i]; print CPSEUDOHASH->{foo}; print CCODE->("me"); print CHASH->[10]; # compile-time error DESCRIPTION =========== This will declare a symbol to be a constant with the given scalar or list value. When you declare a constant such as PI using the method shown above, each machine your script runs upon can have as many digits of accuracy as it can use. Also, your program will be easier to read, more likely to be maintained (and maintained correctly), and far less likely to send a space probe to the wrong planet because nobody noticed the one equation in which you wrote `3.14195'. NOTES ===== The value or values are evaluated in a list context. You may override this with scalar as shown above. These constants do not directly interpolate into double-quotish strings, although you may do so indirectly. (See *Note Perlref: (perl.info)perlref, for details about how this works.) print "The value of PI is @{[ PI ]}.\n"; List constants are returned as lists, not as arrays. $homedir = USERINFO[7]; # WRONG $homedir = (USERINFO)[7]; # Right The use of all caps for constant names is merely a convention, although it is recommended in order to make constants stand out and to help avoid collisions with other barewords, keywords, and subroutine names. Constant names must begin with a letter or underscore. Names beginning with a double underscore are reserved. Some poor choices for names will generate warnings, if warnings are enabled at compile time. Constant symbols are package scoped (rather than block scoped, as `use strict' is). That is, you can refer to a constant from package Other as `Other::CONST'. As with all use directives, defining a constant happens at compile time. Thus, it's probably not correct to put a constant declaration inside of a conditional statement (like `if ($foo) { use constant ... }'). Omitting the value for a symbol gives it the value of undef in a scalar context or the empty list, `()', in a list context. This isn't so nice as it may sound, though, because in this case you must either quote the symbol name, or use a big arrow, (`=>'), with nothing to point to. It is probably best to declare these explicitly. use constant UNICORNS => (); use constant LOGFILE => undef; The result from evaluating a list constant in a scalar context is not documented, and is not guaranteed to be any particular value in the future. In particular, you should not rely upon it being the number of elements in the list, especially since it is not *necessarily* that value in the current implementation. Magical values, tied values, and references can be made into constants at compile time, allowing for way cool stuff like this. (These error numbers aren't totally portable, alas.) use constant E2BIG => ($! = 7); print E2BIG, "\n"; # something like "Arg list too long" print 0+E2BIG, "\n"; # "7" Dereferencing constant references incorrectly (such as using an array subscript on a constant hash reference, or vice versa) will be trapped at compile time. In the rare case in which you need to discover at run time whether a particular constant has been declared via this module, you may use this function to examine the hash `%constant::declared'. If the given constant name does not include a package name, the current package is used. sub declared ($) { use constant 1.01; # don't omit this! my $name = shift; $name =~ s/^::/main::/; my $pkg = caller; my $full_name = $name =~ /::/ ? $name : "${pkg}::$name"; $constant::declared{$full_name}; } TECHNICAL NOTE ============== In the current implementation, scalar constants are actually inlinable subroutines. As of version 5.004 of Perl, the appropriate scalar constant is inserted directly in place of some subroutine calls, thereby saving the overhead of a subroutine call. See `"Constant Functions"', *Note Perlsub: (perl.info)perlsub, for details about how and when this happens. BUGS ==== In the current version of Perl, list constants are not inlined and some symbols may be redefined without generating a warning. It is not possible to have a subroutine or keyword with the same name as a constant in the same package. This is probably a Good Thing. A constant with a name in the list `STDIN STDOUT STDERR ARGV ARGVOUT ENV INC SIG' is not allowed anywhere but in package `main::', for technical reasons. Even though a reference may be declared as a constant, the reference may point to data which may be changed, as this code shows. use constant CARRAY => [ 1,2,3,4 ]; print CARRAY->[1]; CARRAY->[1] = " be changed"; print CARRAY->[1]; Unlike constants in some languages, these cannot be overridden on the command line or via environment variables. You can get into trouble if you use constants in a context which automatically quotes barewords (as is true for any subroutine call). For example, you can't say `$hash{CONSTANT}' because `CONSTANT' will be interpreted as a string. Use `$hash{CONSTANT()}' or `$hash{+CONSTANT}' to prevent the bareword quoting mechanism from kicking in. Similarly, since the `=>' operator quotes a bareword immediately to its left, you have to say `CONSTANT() => 'value'' (or simply use a comma in place of the big arrow) instead of `CONSTANT => 'value''. AUTHOR ====== Tom Phoenix, <`rootbeer@redcat.com'>, with help from many other folks. COPYRIGHT ========= Copyright (C) 1997, 1999 Tom Phoenix This module is free software; you can redistribute it or modify it under the same terms as Perl itself.  File: pm.info, Node: cyrillic, Next: dTemplate, Prev: constant, Up: Module List Library for fast and easy cyrillic text manipulation **************************************************** NAME ==== cyrillic - Library for fast and easy cyrillic text manipulation SYNOPSIS ======== use cyrillic qw/866 win2dos convert locase upcase detect/; print convert( 866, 1251, $str ); print convert( 'dos','win', \$str ); print win2dos $str; DESCRIPTION =========== If first import parameter is number of codepage then locale switched to they codepage. Specialisation (like 'win2dos') call faster then 'convert'. Easy adding new charset. For they need only add charset string. FUNCTIONS ========= At importing list might be listed named convertors. For Ex.: use cyrillic qw/dos2win win2koi mac2dos ibm2dos/; convert SRC_CP, DST_CP, [VAR] Convert VAR from SRC_CP codepage to DST_CP codepage and returns converted string. VAR may be SCALAR or REF to SCALAR. If VAR is REF to SCALAR then SCALAR will be converted. If VAR is ommited then $_ operated. If function called to void context and VAR is not REF then result placed to $_. upcase CODEPAGE, [VAR] Convert VAR to uppercase using CODEPAGE table and returns converted string. VAR may be SCALAR or REF to SCALAR. If VAR is REF to SCALAR then SCALAR will be converted. If VAR is ommited then $_ operated. If function called to void context and VAR is not REF then result placed to $_. locase CODEPAGE, [VAR] Convert VAR to lowercase using CODEPAGE table and returns converted string. VAR may be SCALAR or REF to SCALAR. If VAR is REF to SCALAR then SCALAR will be converted. If VAR is ommited then $_ operated. If function called to void context and VAR is not REF then result placed to $_. detect ARRAY Detect charset of data in ARRAY and returns name of charset. If charset name not detected then returns 'eng'; EXAMPLES ======== use cyrillic qw/convert locase upcase detect dos2win win2dos/; $\ = "\n"; $_ = "\x8F\xE0\xA8\xA2\xA5\xE2 \xF0\xA6\x88\xAA\x88!"; print; upcase 866; print; dos2win; print; win2dos; print; locase 866; print; print detect $_; # EQVIVALENT CALLS: dos2win( $str ); $_ = dos2win( $str ); dos2win( \$str ); $str = dos2win( $str ); dos2win(); dos2win( \$_ ); $_ = dos2win( $_ ); # FOR EASY SWITCH LOCALE CODEPAGE use cyrillic qw/866/; use locale; $str =~ /a-ď/; no locale; $str =~ /a-ď/; AUTHOR ====== Albert MICHEEV COPYRIGHT ========= Copyright (C) 2000, Albert MICHEEV This module is free software; you can redistribute it or modify it under the same terms as Perl itself.  File: pm.info, Node: dTemplate, Next: diagnostics, Prev: cyrillic, Up: Module List A powerful template handling logic with advanced features. ********************************************************** NAME ==== dTemplate - A powerful template handling logic with advanced features. SYNOPSIS ======== use dTemplate; $mail_template = define dTemplate "mail_tmpl.txt";# definition $mail = $mail_template->parse( # parsing TO => "foo@bar.com", SUBJECT => $subject, BODY => sub { $email_type==3 ? $body_for_type_3 : $body_for_others }, SIGNATURE=> $signature_template->parse( KEY => "value" ) ); print "Please send this mail: $mail"; where mail_tmpl.txt is: From : Me To : $TO$ Subject : $SUBJECT$ Message body: $BODY$ $SIGNATURE$ # Advanced feature: Styling $style={lang =>'hungarian',color=>'white'}; # Style definition $html_template = choose dTemplate( $style, # Selector definition 'hungarian+white' => define dTemplate("hun_white_template.html"), 'spanish' => define dTemplate("spanish.html"), 'black+hungarian' => define dTemplate("hun_black_template.html"), 'english' => define dTemplate("english_template.html"), 'empty' => "This is a text, $BODY$ is NOT substituted!!!!"", '' => text dTemplate "$BODY$", # default ); $body_template= choose dTemplate( $style, # Selector definition 'hungarian' => define dTemplate("sziasztok_emberek.html"), 'spanish' => define dTemplate("adios_amigos.html"), '' => define dTemplate("bye_bye.html"), ); print $html_template->parse(BODY => $body_template->parse()); # will print "sziasztok_emberek.html" in the #"hun_white_template.html" %$style=(); print $html_template->parse(BODY => $body_template->parse()); # will print "bye_bye.html" surrounded by "" and "" tags. %$style=( lang => 'english' ); print $html_template->parse(BODY => $body_template->parse()); # will print the "bye_bye.html" in of the "english_template.html" DESCRIPTION =========== This module is aimed to be a simple, general-purpose, lightweight, but very powerful templating system. You can write template-parsing routines in the way the templates are structured logically. Starting from the biggest to the smallest. Your program code will be very clear, structured and easy to understand. This logic can be attained by using inline subroutines as values of template variables. (Look at the example at the end of the document) USAGE ===== First, you need to know how a template looks like, then you need to know how to define a template in a perl program, then you can parse it. After that you can see how to make new encoders. How a template looks like ------------------------- A template is a simple text file, which contains template variable placeholders. The full format of a placeholder is: $Template_Variable%printf_style_format_string*encoder1*encoder2$ Where: Template_Variable It is a mandatory part of the placeholder. Can contain any (locale-aware) alphanumeric characters and '.' . %printf_style_format_string This is an optional part. Used when you want to format the output. You can use as many '%' as you want, it can be good to pad the variable, for example when you parse a table. E.g: $MONEY%%%%%%011d$ is a valid placeholder. There are predefined encoders in the module, which can be used to format the input data. These are: - u : url-encoder - h : HTML-encoder (converts > to >, etc) - uc : convert the string to uppercase - lc : convert the string to lowercase You can use zero or more of these: $TITLE*uc*h$ Read more on encoders (and how to make new encoders) in the Encoders part. Definition of a template ------------------------ There are 3 ways to define a template. $template = define dTemplate $filename This reads the template from a file. $template = text dTemplate $scalar This creates a template from a scalar $template = choose dTemplate $hash, "style1" => $template1, "style2" => ... It is the definition of the template chooser. It is the way how you can create styled templates. Parsing ------- Parsing means substituting the variables which are defined in the template. It can be done by simply calling the "parse" method of a dTemplate object. The parameters of the "parse" method are the substitution definitions. You can provide substitution parameters in two form: - list of name => value pairs - with a hash reference You can mix them if you want: $template->parse( name => $value, { name2 => $value2, name3 => $value3 }, name4 => $value4, { name5 => $value5 }, ... ) The "value" can be: scalar or scalar ref. If a value is scalar, it will be substituted. Scalar refs can be used to save some memory if you use them more than one time. code reference ( sub { }, or \&subroutine ) The sub will be evaluated at each occurence of the template variable. hash You can assign a hash to a template variable if you want. In this way, you can use structured data in the templates, e.g you assign a { name => "Greg", "zip" => 111 } to the template variable "person", and if you use "person.name" in the template, you will get "Greg" back. Nesting (more "."-s) will also work. You can use %dTemplate::parse hash to assign global parse parameters. The return value of the parse method is a dTemplate::Scalar object, which can be used as a simple scalar, but really it is a scalar reference to save some memory. It is useful if you use large templates. Encoders -------- The global hash, %dTemplate::ENCODERS contains the defined encoders. The hash keys are the names, the values are subroutine references. These subs get the encodable data as the first parameter and returns the encoded value. HINTS ===== * In the first parse of every template, the templates will be compiled. It is used to speed up parsing. * Don't forget that %dTemplate::parse can be localized. This means you can define local-only variable assignments in a subroutine: local %dTemplate::parse=( %dTemplate::parse, local_name => $value ); * You don't need to use text as the input value of an encoder, you can use any scalar, even referenes! If you want (for example) print a date by a date encoder, which expects the date to be an array ref of [ year, month, day ], then you can do this, e.g: $dTemplate::ENCODERS{date}=sub { return "" if ref($_[0]) ne 'ARRAY'; return $_[0]->[0]."-".$_[0]->[1]."-".$_[0]->[2]; } Then, when you put $START_DATE*date$ to a template, you can parse this template: $template->parse( START_DATE => [2000,11,13], ... ); ALL-IN-ONE EXAMPLE ================== It is an example, which contains most of the features this module has. It is not intended to be a real-world example, but it can show the usage of this module. This example consists of one program, and some template modules. The executable version of this program can be found in the example directory of the module distribution. use dTemplate; ### definition of the standard templates my @TEMPLATE_LIST=qw(page table_row table_cell); my $templates={}; foreach my $template (@TEMPLATE_LIST) { $templates->{$template} = define dTemplate("templates/$template.htm"); } ### definition of the styled templates (styles = languages) my @STYLES=qw(eng hun); my @STYLED_TEMPLATE_LIST=qw(table_title); my $style_select={ lang => 'hun' }; foreach my $template (@STYLED_TEMPLATE_LIST) { my @array=(); foreach my $style (@STYLES) { push @array, $style => define dTemplate("text/$style/$template.txt"); } $templates->{$template} = choose dTemplate $style_select, @array; } ### setting up input data my $table_to_print=[ [ "Buwam", 3, 6, 9 ], [ "Greg", 8, 4, 2 ], [ "You're", 8, 3, 4 ], [ "HTML chars: <>", 3], ]; ### setting up the global parse hash with parse parameters; $dTemplate::parse{PAGENO}=7; ### settings up a hash with personal data. my $person_hash={ name => { first_name => "Greg" }, zip => "9971", }; ### this hash is simply added to other parse parameters my $parse_hash={ "unknown.data" => 157, }; ### the main page parse routine print $templates->{page}->parse( TABLE_TITLE => # name => value pair $templates->{table_title}->parse(), TABLE => sub { # name => value pair. value is a sub my $ret=""; foreach my $row (@$table_to_print) { $ret .= $templates->{table_row}->parse( BODY => sub { my $ret=""; foreach my $cell (@$row) { $ret .= $templates->{table_cell}->parse( TEXT => $cell, ) } return $ret; } ) } return $ret; }, "person" => $person_hash, # name => value pair. value is a href $parse_hash, # only a hash with parse parameters ); And the templates: templates/page.htm:

$TABLE_TITLE*h$

$TABLE$

Person name: $person.name*h$, zip code: $person.zip*h$
Unknown data: $unknown.data*h$
Page: $PAGENO%02d*h$ templates/table_row.htm: $BODY$ templates/table_cell.htm: $TEXT*h$ text/eng/table_title.txt: Table 1 text/hun/table_title.txt: 1. táblázat COPYRIGHT ========= Copyrigh (c) 2000-2001 Szabó, Balázs (dLux) All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AUTHOR ====== dLux (Szabó, Balázs) SEE ALSO ======== perl(1).