This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: ClearCase/Wrapper/Site, Next: Clone, Prev: ClearCase/Wrapper, Up: Module List site-specific overrides for ClearCase::Wrapper ********************************************** NAME ==== ClearCase::Wrapper::Site - site-specific overrides for ClearCase::Wrapper SYNOPSIS ======== Provides a place to put site-specific enhancements to ClearCase::Wrapper, in order to ease merging of updates. CLEARTOOL ENHANCEMENTS ====================== * SITE_EXAMPLE This is an example of a site-specific enhancement. It's nothing but a demo which prints out its arguments and flags when run. SEE ALSO ======== perl(1), ClearCase::Wrapper  File: pm.info, Node: Clone, Next: CodeBase, Prev: ClearCase/Wrapper/Site, Up: Module List Perl extension for a recurrsive copy of nested objects. ******************************************************* NAME ==== Clone - Perl extension for a recurrsive copy of nested objects. SYNOPSIS ======== use Clone; push @Package::A::ISA, 'Clone'; $a = new Package::A; $b = $a->clone; # or use Clone qw(clone); $b = clone($a,1); DESCRIPTION =========== The Clone module provides a clone method for making recursive copies of nested hash, array, and scalar objects, as well as tied variables. An optional parameter can be used to limit the depth of the copy. AUTHOR ====== Ray Finch, ray@classmates.com Copyright 2000 Ray Finch. This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO ======== perl(1), Storable(3).  File: pm.info, Node: CodeBase, Next: Compress/Bzip2, Prev: Clone, Up: Module List Perl module for accessing dBASE files ************************************* NAME ==== CodeBase - Perl module for accessing dBASE files ABSTRACT ======== The CodeBase module provides a Perl 5 class for accessing dBASE files. It is a development of an earlier unpublished Perl 4 extension. SYNOPSIS ======== Programs using the CodeBase module must include the line: use CodeBase; The functions that the module provides are listed below, grouped according to type of function. File manipulation functions --------------------------- $fh = CodeBase::open($filename, @options); $fh = CodeBase::create($filename, @fielddefs); $fh->DESTROY(); File information functions -------------------------- $n_recs = $fh->reccount(); $recsize = $fh->recsize(); $n_fields = $fh->fldcount(); @names = $fh->names(); $type = $fh->type($fieldname); @fieldinfo = $fh->fieldinfo(); Navigation functions -------------------- $recno = $fh->recno(); $fh->goto($recno); $fh->skip($n_recs); $fh->bof(); $fh->eof(); Record manipulation functions ----------------------------- @values = $fh->fields(); $value = $fh->field($fieldname); $fh->set_field($fieldname, $value); $fh->new_record(@values); $fh->replace_record(@values); $fh->deleted(); $fh->delete_record($recno); $fh->flush($tries); $fh->pack($compress_memo); $fh->lock($what, $tries); $fh->unlock(); Index manipulation functions ---------------------------- $n_tags = $fh->tag_count(); @tags = $fh->tags(); @taginfo = $fh->taginfo($index_name); $fh->open_index($name); $fh->create_index($name, $taginfo); $fh->reindex(); $fh->set_tag(); $fh->seek($key); $q = $fh->prepare_query($expr [, $sortexpr [, $desc]]); $q->execute; $q->next([$skip]); Miscellaneous functions ----------------------- CodeBase::option(@options); $errno = CodeBase::errno(); $errmsg = CodeBase::errmsg($errno); $version = CodeBase::libversion; $dbtype = CodeBase::dbtype; DESCRIPTION =========== Each function provided by the CodeBase module is described below. The module uses the CodeBase library from Sequiter Software Inc., which is a C library providing database management functions for dBASE files. File manipulation functions --------------------------- Existing dBASE files can be opened with open() and new files created with create(). Files are implicit closed by the DESTROY method, which is called when all references to the internal file handle go out of scope. open FILENAME [, OPTION-KEYWORD ...] Opens the named dBASE file and returns a file handle which can be used in other CodeBase functions. The filename should omit the `.dbf' extension. The following options keywords are recognized: `"readonly"', `"noindex"' or `"exclusive"' (`"ro"' is a synonym for `"readonly"' and `"x"' is a synonym for `"exclusive"'). Option keywords are case-insensitive. For example to open the file `books.dbf' in read-only mode, without opening the production index: $fh = CodeBase::open("books", "readonly", "noindex"); create FILENAME, FIELD-DEFS =item create FILENAME, FIELD-DEF-ARRAY, INDEX-TAG Creates a new dBASE file using the field definitions specified and returns a file that can be used in other CodeBase functions. The field definitions consist of an array of alternating pairs of field name and field type. @field_defs = ( "F1" => "C10", "F2" => "N4" ); $fh = CodeBase::create("test", @field_defs); The field types are as follows: Type Code Length Decimals ------------------------------------------- Character C 1 to 65533 0 Date D 8 0 F.P. F 1 to 19 0 to len - 2 Logical L 1 0 Memo M 10 0 Numeric N 1 to 19 0 to len - 2 Note: create does not create a production index file - use create_index with an empty filename. The facility to create a production index at the same time that a database is created may be added later. Field and tag information arguments would then be specified as references. DESTROY FILEHANDLE The DESTROY function is not normally called explicitly. It is invoked automatically when all copies of the file handle generated by open() or create() go out of scope. For example: { my($fh2); { $fh1 = CodeBase::open("test"); $fh2 = $fh1; } # $fh1 is destroyed here, but $fh2 contains a copy of the file # handle so CodeBase::DESTROY is not called yet. } # $fh2 is destroyed as it goes out of scope, so CodeBase::DESTROY # is invoked. Navigation functions -------------------- recno Returns the current record number. It is equivalent to the dBASE `RECNO()' function. $recno = $fh->recno If the file has just been opened, created or packed there is no current record number and `recno()' will return undef. goto RECNO Positions the current record of the database file to the specified record. It is equivalent to the dBASE GOTO statement. $fh->goto($recno); The record number for `CodeBase::goto' should be an integer between 1 and `CodeBase::reccount'. It can also take one of the keywords: `"TOP"' or `"BOTTOM"'. The keywords `"START"' and `"FIRST"' are accepted as synonyms for `"TOP"', and `"END"' and `"LAST"' as synonyms for `"BOTTOM"'. Only the first character of a keyword is significant and case is not significant. Normally goto returns 1 to signify success; if an error occurs it returns undef. The error code can then be retrieved with errno. skip N_RECORDS Skips forwards or backwards in the database file by the specified number of fields. It is equivalent to the dBASE SKIP statement. The number of fields defaults to one. $fh->skip($n_records); Normally skip returns the new record number; if an error occurs it returns undef. The error code can then be retrieved with errno. bof Returns a boolean value indicating whether the current record is positioned before the first record. It is equivalent to the dBASE `BOF()' function. if ($fh->bof()) ... eof Returns a boolean value indicating whether the current record is positioned at the end of the file. It is equivalent to the dBASE `EOF()' function. while (!$fh->eof()) ... Record handling functions ------------------------- reccount Returns the number of records in the database file. It is equivalent to the dBASE `RECCOUNT()' function. $n_recs = $fh->reccount(); recsize Returns the size in bytes of records in the database file (including the deletion flag). It is equivalent to the dBASE `RECWIDTH()' function. $recsize = $fh->recsize(); fldcount Returns the number of fields per record for the database file. $n_fields = $fh->fldcount(); It is equivalent to the dBASE `FLDCOUNT()' function. names Returns the field names as an array. @names = $fh->names(); type FIELD Returns the type of the named field as a string. $type = $fh->type("field1"); fieldinfo [NAMES] Returns an array containing information about the specified fields or about all fields if no fields are specified. For example if the database open on $fh contains, amongst others, the fields `field1' and `field2' as a 12 character field and a 10 byte numeric field with 3 decimal places respectively then: @names = ("field1, "field2"); $fh->fieldinfo(@names); would return an array containing the values: ("field1", "C12", "field2", "N10.3") This is a shortcut function. The same information can be built up by using names and type: foreach $name ($fh->names) { push(@results, ($name, $fh->type($name))); } values [NAMES] Returns an array containing the values of each of the specified fields, or of all fields if no field names are specified. @values = $fh->values("field1", "field3"); field NAME Returns the value of the named field. $value = $fh->field("field1"); set_field NAME, VALUE Sets the value of the named field to the specified value. $fh->set_field("field1", $value); If the field is a date field the value should be formatted in dBASE date format (e.g. `"YYYYMMDD"') or should be one of the keywords `"YESTERDAY"', `"TODAY"' or `"TOMORROW"' (the keywords are not case sensitive) or may be a number of days to the current date specified as `+num' or `-num'. For example to set a date field to a week's time: $fh->set_field("date", "+7"); new_record VALUES Creates a new record using the values specified. `VALUES' may be an array of field values: $fh->new_record({ firstname => "Fred", surname => "Bloggs" }); or a reference to a hash, the keys of which are the field names: $fh->new_record("Bloggs", "Fred"); If the values are supplied as an array, a value must be supplied for each field. If the values are supplied as a hash unspecified fields are filled with blanks. Excess array values or hash keys that are not names of fields are simply ignored. The handling of date fields is as described under set_field. replace_record VALUES Replaces the fields of the current record with the values specified. As with new_record `VALUES' may be an array of field values: $fh->replace_record("Bloggs", "Fred"); or a reference to a hash, the keys of which are the field names. $fh->replace_record({ firstname => "Fred", surname => "Bloggs" }); In the former case a value must be supplied for each field, while in the latter case unspecified fields are unchanged. Excess values or hash keys that are not names of fields are ignored. The handling of date fields is as described under set_field. deleted Returns a boolean value indicating whether the current record is deleted. if ($fh->deleted()) ... This function is equivalent to the dBASE `DELETED()' function. delete_record [RECNO] Deletes the record specified or the current record if called without a record number. $fh->delete_record($recno); recall_record [RECNO] Recalls the record specified or the current record if called without a record number. (Not yet implemented). flush [TRIES] Flushes to file any outstanding changes (made by `set_field()'. Records need to be locked while changes are written. `TRIES' is the number of attempts that should be made to aquire the lock. Subsequent attempts are made with a one second interval. pack COMPRESS-MEMO-FLAG Packs the database file removing deleted records. If flag parameter is specified as true then memo fields are compressed at the same time: $fh->pack(1); lock WHAT [, TRIES] Locks the specified record or the whole file. `WHAT' should either be `"FILE"' or a record number (the current record can be referred to as `"."'. `TRIES' is the number of attempts that should be made to aquire the lock. Subsequent attempts are made with a one second interval. unlock Removes any existing locks on the file. Index Handling Functions ------------------------ A production index file is automatically opened when a database file is opened, if it exists unless the noindex option is specified. An index file can be opened with the open_index method. tagcount Returns the number of index tags. $n_tags = $fh->tagcount(); tags Returns an array containing the names of all the tags associated with the database file. @tags = $fh->tags(); set_tag TAG Sets the current index tag to the named tag. If no tag is specified the currently selected tag is deselected. $fh->set_tag("TAG1") || die "Cannot set index tag.\n"; taginfo Returns an array containing information about tags. Each element of the array is a reference to a hash containing attributes of the tag. The attributes are name, expression, filter, order and `duplicates'. This array is suitable for passing to create_index, for example for copying the index structure of a file: @taginfo = $fh1->taginfo; $fh2->create_index(undef, \@taginfo); create_index NAME, TAGINFO Creates a new index file. The index file name is specified by NAME and should not include the `.mdx' extension. If NAME is specified as undef or "" a production index is created. The new index file will contain the tags specified in the `TAGINFO' argument: an array passed by reference, each element of which is a hash containing attributes of the particular tag. Valid attributes are: name, expression, filter, `duplicates' and order. For example to create a production index with three tags: $fh->create_index( undef, [ { name => "TAG1", expression => "F1", duplicates => "KEEP" }, { name => "TAG2", expression => "F2", order => "DESCENDING" }, { name => "TAG3", expression => "UPPER(F3)" } ] ); open_index [ NAME ] Opens the specified index file. The name should not include the `.mdx' extension. If the name is not specified then the production index is opened. seek VALUE Seeks in the currently selected index tag for a match for the specified value. Returns 1 if a match is found otherwise the undefined value is returned and the error code can be retrieved with CodeBase::errno. The search value must be formatted correctly for the index, for example if an index is generted on `STR(F1)', where `F1' is a numeric field of width 6, the value be formatted as a right aligned 6-character integer: $fh->seek(" 42"); For string valued index keys a search value shorter than the tag expression length will be matched on the initial substring, e.g. `"FRED"' would match `"FREDERICK"'. Query functions --------------- The query functions interface to the CodeBase Relate/Query module. The interface is currently incomplete. All that is provided is the facility to query a single file. A query is prepared (in a similar manner to the Perl DBI query) and then executed and the result set stepped through. The functions are: $q = $fh->prepare_query($expr [, $sortexpr [, $desc]]); $q->execute; $q->next([$skip]); An example of the usage would be: $q = $fh->prepare_query('AGE >= 18 .AND. AGE <= 65', 'AGE', 1); $q->execute; while (my $r = $q->next) { @fields = $r->values; # do some processing. } I intend to allow more complex queries to be built up in a Perl-ish manner, but I haven't come up with an interface yet. Miscellaneous functions ----------------------- CodeBase::option OPTIONS Sets configuration options for the CodeBase module. The only option currently offered is trace. Setting this to a non-zero value enables the output of tracing, which can be helpful in debugging. # Enable tracing CodeBase::option("trace=1"); # Disable tracing CodeBase::option("trace=0"); CodeBase::errno Returns the error code for the last operation. CodeBase::errmsg ERRNO Returns an explanatory string for the error code ERRNO CodeBase::libversion Returns the version of the CodeBase library that the module was compiled and linked against. CodeBase::dbformat Returns the XBase file format that the library and module were compiled for. This will be one of "dBASE IV", "FoxPro" or "Clipper". ERRORS ====== Functions return a value on success and undef on error. The error code can be determined by calling CodeBase::errno, and the equivalent error message by calling CodeBase::errmsg. A number of variables are defined as symbolic names for the CodeBase error codes. Thes variables are all defined in the `CodeBase' package and so need to be referred with the package prefix (e.g. `$CodeBase::e4close'). *General disk access errors* $e4close = -10; # Closing file $e4create = -20; # Creating file $e4len = -30; # Determining file length $e4len_set = -40; # Setting file length $e4lock = -50; # Locking file $e4open = -60; # Opening file $e4read = -70; # Reading file $e4remove = -80; # Removing file $e4rename = -90; # Renaming file $e4seek = -100; # Seeking to a file position $e4unlock = -110; # Unlocking file $e4write = -120; # Writing to file *Data file specific errors* $e4data = -200; # File is not a data file $e4field_name = -210; # Unrecognized field name $e4field_type = -220; # Unrecognized field type $e4record_len = -230; # Record length too large *Index file specific errors* $e4entry = -300; # Tag entry missing $e4index = -310; # Not a correct index file $e4tag_name = -330; # Tag name not found $e4unique = -340; # Unique key error *Expression evaluation errors* $e4comma_expected = -400; # Comma or bracket expected $e4complete = -410; # Expression not complete $e4data_name = -420; # Data file name not located $e4length_err = -422; # IIF() needs parameters of same length $e4not_constant = -425; # SUBSTR() and STR() need constant parameters $e4num_params = -430; # Number of parameters is wrong $e4overflow = -440; # Overflow while evaluating expression $e4right_missing = -450; # Right bracket missing $e4type_sub = -460; # Sub-expression type is wrong $e4unrec_function = -470; # Unrecognized function $e4unrec_operator = -480; # Unrecognized operator $e4unrec_value = -490; # Unrecognized value $e4unterminated = -500; # Unterminated string *Optimization errors* $e4opt = -610; # Optimization error $e4opt_suspend = -620; # Optimization removal error $e4opt_flush = -630; # Optimization file flushing failure *Relation errors* (not used) $e4relate = -710; # Relation error $e4lookup_err = -720; # Matching slave record not located *Severe errors* $e4info = -910; # Unexpected information $e4memory = -920; # Out of memory $e4parm = -930; # Unexpected parameter $e4result = -950; # Unexpected result For detailed explanations of these codes refer to the *CodeBase Reference Guide* by Sequiter Software Inc. RESTRICTIONS ============ Tags cannot be added to existing index files - the entire index file must be recreated. This is a restriction imposed by CodeBase 5.1. FUTURE DIRECTIONS ================= Record fields may be made into an associative array allowing their values to be accessed and set with the following syntax: $val = $file->{"F1"}; # rather than: $val = $file->value("F1"); $file->{"F1"} = $newval; # rather than: $file->set_value("F1", $newval); The query functionality will be expanded. COMPATIBILTY ============ CodeBase Functions ------------------ CodeBase 6.4 CodeBase 5.1 CodeBase.pm ============ ============ =========== code4calcCreate expr4calc_create code4calcReset expr4calc_reset code4close d4close_all implicit on exit code4connect code4data d4data code4dateFormat code4dateFormatSet code4exit e4exit code4flush d4flush_files code4indexExtension code4init d4init code4initUndo d4init_undo code4lock code4lockClear code4lockFileName code4lockItem code4lockNetworkId code4lockUserId code4logCreate code4logFileName code4logOpen code4logOpenOff code4optAll code4optStart d4opt_start code4optSuspend d4opt_suspend code4timeout code4timeoutSet code4tranCommit code4tranRollback code4tranStart code4tranStatus code4unlock d4unlock_files code4unlockAuto code4unlockAutoSet Data File Functions ------------------- CodeBase 6.4 CodeBase 5.1 CodeBase.pm ============ ============ =========== d4alias d4alias d4aliasSet d4alias_set d4append d4appendBlank d4append_blank d4appendStart d4append_start d4blank d4bottom d4changed d4check d4close d4close undef $fh d4create d4delete d4deleted d4eof d4field d4fieldInfo d4field_info d4fieldJ d4field_j d4fieldNumber d4field_number d4fileName d4flush d4flush $fh->flush d4flushData d4flush_data d4freeBlocks d4free_blocks d4go d4go $fh->go d4goBof d4go_bof d4goData d4go_data d4goEof d4go_eof d4index d4lock d4lockAdd d4lockAddAll d4lockAddAppend d4lockAddFile d4lockAll d4lock_all d4lockAppend d4lock_append d4lockFile d4lock_file $fh->lock('FILE') d4lockIndex d4lock_index d4lockTest d4lock_test d4lockTestAppend d4lock_test_append d4lockTestFile d4lock_test_file d4log d4logStatus d4memoCompress d4memo_compress d4numFields d4num_fields $fh->fldcount d4open d4open $fh = CodeBase::open($file ...) d4openClone d4optimize d4optimizeWrite d4optimize_write d4pack d4pack d4packData d4pack_data d4position d4position d4positionSet d4position_set d4recall d4recall d4recCount d4reccount d4recNo d4recno $fh->recno d4record d4recPosition d4record_position d4recWidth d4record_width $fh->recsize d4refresh d4refresh $fh->refresh d4refreshRecord d4refresh_record d4reindex d4reindex d4remove d4seek d4seek $fh->seek d4seekDouble d4seek_double d4seekN d4seek_n d4seekNext d4seekNextDouble d4seekNextN d4skip d4skip $fh->skip d4tag d4tag d4tagDefault d4tag_default d4tagNext d4tag_next d4tagPrev d4tag_prev d4tagSelect d4tag_select d4tagSelected d4tag_selected d4tagSync d4top d4top d4unlock d4unlock d4write d4write d4writeData d4write_data d4writeKeys d4write_keys d4zapData d4zap_data Date Functions -------------- date4formatMdx date4format_mdx date4formatMdx2 date4format_mdx2 date4timeNow date4time_now dfile4updateHeader d4update_header e4exitTest e4exit_test error4code e4code error4set e4set expr4calcDelete expr4calc_delete expr4calcLookup expr4calc_lookup expr4calcMassage expr4calc_massage expr4calcModify expr4calc_modify expr4calcNameChange expr4calc_name_change expr4keyConvert expr4key_convert expr4keyLen expr4key_len Field Functions --------------- f4assignChar f4assign_char $fh->field_set($name, $value) f4assignDouble f4assign_double f4assignField f4assign_field f4assignInt f4assign_int f4assignLong f4assign_long f4assignN f4assign_n f4assignPtr f4assign_ptr f4memoAssign f4memo_assign f4memoAssignN f4memo_assign_n f4memoFree f4memo_free f4memoLen f4memo_len f4memoNcpy f4memo_ncpy f4memoPtr f4memo_ptr f4memoSetLen f4memo_set_len f4memoStr f4memo_str file4lenSet file4len_set file4lockHook file4lock_hook file4optimizeWrite file4optimize_write file4readAll file4read_all file4readError file4read_error file4seqRead file4seq_read file4seqReadAll file4seq_read_all file4seqReadInit file4seq_read_init file4seqWrite file4seq_write file4seqWriteFlush file4seq_write_flush file4seqWriteInit file4seq_write_init file4seqWriteRepeat file4seq_write_repeat i4tagAdd i4add_tag i4tagInfo i4tag_info relate4createSlave relate4create_slave relate4doAll relate4do relate4doOne relate4do_one relate4errorAction relate4error_action relate4freeRelate relate4free_relate relate4matchLen relate4match_len relate4querySet relate4query_set relate4skipEnable relate4skip_enable relate4sortSet relate4sort_set t4addCalc t4add_calc t4uniqueSet t4unique_set tfile4add t4add(a)->tagFile, b, c tfile4block t4block(a)->tagFile tfile4bottom t4bottom( (a)->tagFile tfile4down t4down( (a)->tagFile tfile4dskip t4dskip(a)->tagFile, b tfile4dump t4dump(a)->tagFile, b, c tfile4eof t4eof(a)->tagFile tfile4flush t4flush(a)->tagFile tfile4freeAll t4free_all(a)->tagFile tfile4go t4go(a)->tagFile, b, c, 0 tfile4isDescending t4is_descending(a)->tagFile tfile4key t4key(a)->tagFile tfile4position t4position(a)->tagFile tfile4positionSet t4position_set(a)->tagFile, b tfile4recNo t4recno(a)->tagFile tfile4remove t4remove(a)->tagFile, b, c tfile4removeCalc t4remove_calc(a)->tagFile, b tfile4seek t4seek(a)->tagFile, b, c tfile4skip t4skip(a)->tagFile, b tfile4top t4top(a)->tagFile tfile4up t4up(a)->tagFile tfile4upToRoot t4up_to_root(a)->tagFile Unsupported functions --------------------- Many lower level functions are not directly accessible from CodeBase.pm. These include: * conversion functions (c4xxx) * linked list functions (l4xxx) * memory functions (m4xxx) * sort functions (sort4xxx) * utility functions (u4xxx) COPYRIGHT AND TRADEMARKS ======================== The CodeBase module is Copyright (C) 1996-1999, Andrew Ford and Ford & Mason Ltd. All rights reserved. The CodeBase library is copyright Sequiter Software, Inc. CodeBase is a trademark of Sequiter Software, Inc. AUTHOR ====== Andrew Ford (andrew@icarus.demon.co.uk) SEE ALSO ======== The Perl reference manual, especially the following sections: *perlmod* (modules), *perldata* (data types), *perlobj* (objects), *perlref* (references and nested data structures), *perldsc* (data structures cookbook), *perllol* (manipulating lists of lists). The second edition of *Programming Perl* by Larry Wall and Randal L. Schwarz (O'Reilly and Associates) covers Perl 5. The *CodeBase Reference Guide* and the *CodeBase User Guide*, both from Sequiter Software Inc. cover the underlying C library.  File: pm.info, Node: Compress/Bzip2, Next: Compress/LZF, Prev: CodeBase, Up: Module List Interface to Bzip2 compression library ************************************** NAME ==== Compress::Bzip2 - Interface to Bzip2 compression library SYNOPSIS ======== use Compress::Bzip2; $dest = Compress::Bzip2::compress($source, [$level]); $dest = Compress::Bzip2::decompress($source); DESCRIPTION =========== The *Compress::Bzip2* module provides a Perl interface to the *Bzip2* compression library (see `' in this node for details about where to get *Bzip2*). A relevant subset of the functionality provided by *Bzip2* is available in *Compress::Bzip2*. All string parameters can either be a scalar or a scalar reference. COMPRESSION FUNCTIONS ===================== $dest = Compress::Bzip2::compress($string) Compress a string using the default compression level, returning a string containing compressed data. $dest = Compress::Bzip2::compress($string, $level) Compress string, using the chosen compression level (either 1 or 9). Return a string containing the compressed data. On error undef is returned. DECOMPRESSION FUNCTIONS ======================= $dest = Compress::Bzip2::decompress($string) Decompress the data in string, returning a string containing the decompressed data. On error undef is returned. AUTHOR ====== The *Compress::Bzip2* module was written by Gawdi Azem `azemgi@rupert.informatik.uni-stuttgart.de'. MODIFICATION HISTORY ==================== 1.00 First public release of *Compress::Bzip2*.  File: pm.info, Node: Compress/LZF, Next: Compress/LZO, Prev: Compress/Bzip2, Up: Module List extremely leight-weight Lev-Zimpel-Free compression *************************************************** NAME ==== Compress::LZF - extremely leight-weight Lev-Zimpel-Free compression SYNOPSIS ======== use Compress::LZF; $compressed = compress $uncompressed_data; $original_data = decompress $compressed; DESCRIPTION =========== LZF is an extremely fast (not that much slower than a pure memcpy) compression algorithm. It is ideal for applications where you want to save some space but not at the cost of speed. It is ideal for repetitive data as well. The module is self-contained and very small (no large library to be pulled in). It is also free, so there should be no problems incoporating this module into commercial programs. I have no idea wether any patents in any countries apply to this algorithm, but at the moment it is believed that it is free from any patents. FUNCTIONS ========= $compressed = compress $uncompressed ------------------------------------ Try to compress the given string as quickly and as much as possible. In the worst case, the string can enlarge by 1 byte, but that should be the absolute exception. You can expect a 45% compression ratio on large, binary strings. $decompressed = decompress $compressed -------------------------------------- Uncompress the string (compressed by compress) and return the original data. Decompression errors can result in either broken data (there is no checksum kept) or a runtime error. SEE ALSO ======== Other Compress::* modules, especially Compress::LZV1 (an older, less speedy module that guarentees only 1 byte overhead worst case) and Compress::Zlib. http://liblzf.plan9.de/ AUTHOR ====== This perl extension and the underlying liblzf were written by Marc Lehmann (See also http://liblzf.plan9.de/). BUGS ====  File: pm.info, Node: Compress/LZO, Next: Compress/LZV1, Prev: Compress/LZF, Up: Module List Interface to LZO compression library ************************************ NAME ==== Compress::LZO - Interface to LZO compression library SYNOPSIS ======== use Compress::LZO; $dest = Compress::LZO::compress($source, [$level]); $dest = Compress::LZO::decompress($source); $dest = Compress::LZO::optimize($source); $crc = Compress::LZO::adler32($buffer [,$crc]); $crc = Compress::LZO::crc32($buffer [,$crc]); LZO_VERSION, LZO_VERSION_STRING, LZO_VERSION_DATE DESCRIPTION =========== The *Compress::LZO* module provides a Perl interface to the *LZO* compression library (see `' in this node for details about where to get *LZO*). A relevant subset of the functionality provided by *LZO* is available in *Compress::LZO*. All string parameters can either be a scalar or a scalar reference. COMPRESSION FUNCTIONS ===================== $dest = Compress::LZO::compress($string) Compress a string using the default compression level, returning a string containing compressed data. $dest = Compress::LZO::compress($string, $level) Compress string, using the chosen compression level (either 1 or 9). Return a string containing the compressed data. On error undef is returned. DECOMPRESSION FUNCTIONS ======================= $dest = Compress::LZO::decompress($string) Decompress the data in string, returning a string containing the decompressed data. On error undef is returned. OPTIMIZATION FUNCTIONS ====================== $dest = Compress::LZO::optimize($string) Optimize the representation of the compressed data, returning a string containing the compressed data. On error undef is returned. CHECKSUM FUNCTIONS ================== Two functions are provided by *LZO* to calculate a checksum. For the Perl interface, the order of the two parameters in both functions has been reversed. This allows both running checksums and one off calculations to be done. $crc = Compress::LZO::adler32($string [,$crc]) ; $crc = Compress::LZO::crc32($string [,$crc]) ; AUTHOR ====== The *Compress::LZO* module was written by Markus F.X.J. Oberhumer `markus.oberhumer@jk.uni-linz.ac.at'. The latest copy of the module should also be found on CPAN in `modules/by-module/Compress/perl-lzo-x.x.tar.gz'. The *LZO* compression library was written by Markus F.X.J. Oberhumer `markus.oberhumer@jk.uni-linz.ac.at'. It is available from the LZO home page at `http://wildsau.idv.uni-linz.ac.at/mfx/lzo.html'. MODIFICATION HISTORY ==================== 1.00 First public release of *Compress::LZO*.  File: pm.info, Node: Compress/LZV1, Next: Compress/Zlib, Prev: Compress/LZO, Up: Module List extremely leight-weight Lev-Zimpel-Vogt compression *************************************************** NAME ==== Compress::LZV1 - extremely leight-weight Lev-Zimpel-Vogt compression SYNOPSIS ======== use Compress::LZV1; $probably_compressed = compress $uncompressed_data; $original_data = uncompress $probably_compressed; DESCRIPTION =========== LZV1 is an extremely fast (not that much slower than a pure memcpy) compression algorithm. It is ideal for applications where you want to save some space but not at the cost of speed. It is ideal for repetitive data as well. The module is self-contained and very small (no large library to be pulled in). I have no idea wether any patents in any countries apply to this algorithm, but at the moment it is believed that it is free from any patents. FUNCTIONS ========= $compressed = compress $uncompressed ------------------------------------ Try to compress the given string as quickly and as much as possible. In the worst case, the string can enlarge by at most a single byte. Empty strings yield empty strings. The uncompressed data string must be smaller than 16MB (1<<24). The compressed is (currently) in one of two forms: * a literal 'U', followed by the original, uncompressed data * a literal 'L', followed by three bytes (big-endian) uncompressed length, followed by the actual LZV1 data $decompressed = decompress $compressed -------------------------------------- Uncompress the string (compressed by compress) and return the original data. Decompression errors can result in either broken data (there is no checksum kept) or a runtime error. SEE ALSO ======== Other Compress::* modules, especially Compress::LZO (for speed) and Compress::Zlib. AUTHOR ====== This perl extension was written by Marc Lehmann (See also http://www.goof.com/pcg/marc/). The original lzv1 code was written by Hermann Vogt and put under the GPL. (There is also a i386 assembler version that is not used in this module). The lzv1 code was accompanied by the following comment: The method presented here is faster and compresses better than lzrw1 and lzrw1-a. I named it lzv for "Lev-Zimpel-Vogt". It uses ideas introduced by Ross Williams in his algorithm lzrw1 [R. N. Williams (1991): "An Extremly Fast ZIV-Lempel Data Compression Algorithm", Proceedings IEEE Data Compression Conference, Snowbird, Utah, 362-371] and by Fiala and Green in their algorithm a1 [E. R. Fiala, D. H. Greene (1989): "Data Compression with Finite Windows", Communications of the ACM, 4, 490-505]. Because lzv differs strongly from both, I hope there will be no patent problems. The hashing-method has been stolen from Jean-loup Gailly's (patent free) gzip. BUGS ==== It seems that the c-code has _big_ alignment problems :(  File: pm.info, Node: Compress/Zlib, Next: Config, Prev: Compress/LZV1, Up: Module List Interface to zlib compression library ************************************* NAME ==== Compress::Zlib - Interface to zlib compression library SYNOPSIS ======== use Compress::Zlib ; ($d, $status) = deflateInit( [OPT] ) ; ($out, $status) = $d->deflate($buffer) ; ($out, $status) = $d->flush() ; $d->dict_adler() ; ($i, $status) = inflateInit( [OPT] ) ; ($out, $status) = $i->inflate($buffer) ; $i->dict_adler() ; $dest = compress($source) ; $dest = uncompress($source) ; $gz = gzopen($filename or filehandle, $mode) ; $bytesread = $gz->gzread($buffer [,$size]) ; $bytesread = $gz->gzreadline($line) ; $byteswritten = $gz->gzwrite($buffer) ; $status = $gz->gzflush($flush) ; $status = $gz->gzclose() ; $errstring = $gz->gzerror() ; $gzerrno $dest = Compress::Zlib::memGzip($buffer) ; $dest = Compress::Zlib::memGunzip($buffer) ; $crc = adler32($buffer [,$crc]) ; $crc = crc32($buffer [,$crc]) ; ZLIB_VERSION DESCRIPTION =========== The *Compress::Zlib* module provides a Perl interface to the *zlib* compression library (see `' in this node for details about where to get *zlib*). Most of the functionality provided by *zlib* is available in *Compress::Zlib*. The module can be split into two general areas of functionality, namely in-memory compression/decompression and read/write access to *gzip* files. Each of these areas will be discussed separately below. DEFLATE ======= The interface *Compress::Zlib* provides to the in-memory *deflate* (and *inflate*) functions has been modified to fit into a Perl model. The main difference is that for both inflation and deflation, the Perl interface will always consume the complete input buffer before returning. Also the output buffer returned will be automatically grown to fit the amount of output available. Here is a definition of the interface available: ($d, $status) = deflateInit( [OPT] ) ------------------------------------ Initialises a deflation stream. It combines the features of the *zlib* functions *deflateInit*, *deflateInit2* and *deflateSetDictionary*. If successful, it will return the initialised deflation stream, $d and $status of `Z_OK' in a list context. In scalar context it returns the deflation stream, $d, only. If not successful, the returned deflation stream ($d) will be undef and $status will hold the exact *zlib* error code. The function optionally takes a number of named options specified as `-Name=>value' pairs. This allows individual options to be tailored without having to specify them all in the parameter list. For backward compatibility, it is also possible to pass the parameters as a reference to a hash containing the name=>value pairs. The function takes one optional parameter, a reference to a hash. The contents of the hash allow the deflation interface to be tailored. Here is a list of the valid options: *-Level* Defines the compression level. Valid values are 1 through 9, `Z_BEST_SPEED', `Z_BEST_COMPRESSION', and `Z_DEFAULT_COMPRESSION'. The default is `-Level =>Z_DEFAULT_COMPRESSION'. *-Method* Defines the compression method. The only valid value at present (and the default) is `-Method =>Z_DEFLATED'. *-WindowBits* For a definition of the meaning and valid values for *WindowBits* refer to the *zlib* documentation for *deflateInit2*. Defaults to `-WindowBits =>MAX_WBITS'. *-MemLevel* For a definition of the meaning and valid values for *MemLevel* refer to the *zlib* documentation for *deflateInit2*. Defaults to `-MemLevel =>MAX_MEM_LEVEL'. *-Strategy* Defines the strategy used to tune the compression. The valid values are `Z_DEFAULT_STRATEGY', `Z_FILTERED' and `Z_HUFFMAN_ONLY'. The default is `-Strategy =>Z_DEFAULT_STRATEGY'. *-Dictionary* When a dictionary is specified *Compress::Zlib* will automatically call *deflateSetDictionary* directly after calling *deflateInit*. The Adler32 value for the dictionary can be obtained by calling the method `$d-'dict_adler()>. The default is no dictionary. *-Bufsize* Sets the initial size for the deflation buffer. If the buffer has to be reallocated to increase the size, it will grow in increments of *Bufsize*. The default is 4096. Here is an example of using the *deflateInit* optional parameter list to override the default buffer size and compression level. All other options will take their default values. deflateInit( -Bufsize => 300, -Level => Z_BEST_SPEED ) ; *($out, $status) = $d->deflate($buffer)* ---------------------------------------- Deflates the contents of *$buffer*. The buffer can either be a scalar or a scalar reference. When finished, *$buffer* will be completely processed (assuming there were no errors). If the deflation was successful it returns the deflated output, *$out*, and a status value, $status, of `Z_OK'. On error, *$out* will be undef and $status will contain the *zlib* error code. In a scalar context *deflate* will return *$out* only. As with the *deflate* function in *zlib*, it is not necessarily the case that any output will be produced by this method. So don't rely on the fact that *$out* is empty for an error test. *($out, $status) = $d->flush([flush_type])* ------------------------------------------- Finishes the deflation. Any pending output will be returned via *$out*. $status will have a value `Z_OK' if successful. In a scalar context flush will return *$out* only. Note that flushing can degrade the compression ratio, so it should only be used to terminate a decompression. By default the `flush_type' used is `Z_FINISH'. Other valid values for `flush_type' are Z_NO_FLUSH, Z_PARTIAL_FLUSH, Z_SYNC_FLUSH and Z_FULL_FLUSH. It is strongly recommended that you only set the `flush_type' parameter if you fully understand what it does. See the `zlib' documentation for details. *$d->dict_adler()* ------------------ Returns the adler32 value for the dictionary. Example ------- Here is a trivial example of using *deflate*. It simply reads standard input, deflates it and writes it to standard output. use strict ; use warnings ; use Compress::Zlib ; binmode STDIN; binmode STDOUT; my $x = deflateInit() or die "Cannot create a deflation stream\n" ; my ($output, $status) ; while (<>) { ($output, $status) = $x->deflate($_) ; $status == Z_OK or die "deflation failed\n" ; print $output ; } ($output, $status) = $x->flush() ; $status == Z_OK or die "deflation failed\n" ; print $output ; INFLATE ======= Here is a definition of the interface: ($i, $status) = inflateInit() ----------------------------- Initialises an inflation stream. In a list context it returns the inflation stream, $i, and the *zlib* status code ($status). In a scalar context it returns the inflation stream only. If successful, $i will hold the inflation stream and $status will be `Z_OK'. If not successful, $i will be undef and $status will hold the *zlib* error code. The function optionally takes a number of named options specified as `-Name=>value' pairs. This allows individual options to be tailored without having to specify them all in the parameter list. For backward compatibility, it is also possible to pass the parameters as a reference to a hash containing the name=>value pairs. The function takes one optional parameter, a reference to a hash. The contents of the hash allow the deflation interface to be tailored. Here is a list of the valid options: *-WindowBits* For a definition of the meaning and valid values for *WindowBits* refer to the *zlib* documentation for *inflateInit2*. Defaults to `-WindowBits =>MAX_WBITS'. *-Bufsize* Sets the initial size for the inflation buffer. If the buffer has to be reallocated to increase the size, it will grow in increments of *Bufsize*. Default is 4096. *-Dictionary* The default is no dictionary. Here is an example of using the *inflateInit* optional parameter to override the default buffer size. inflateInit( -Bufsize => 300 ) ; *($out, $status) = $i->inflate($buffer)* ---------------------------------------- Inflates the complete contents of *$buffer*. The buffer can either be a scalar or a scalar reference. Returns `Z_OK' if successful and `Z_STREAM_END' if the end of the compressed data has been successfully reached. If not successful, *$out* will be undef and $status will hold the *zlib* error code. The `$buffer' parameter is modified by `inflate'. On completion it will contain what remains of the input buffer after inflation. This means that `$buffer' will be an empty string when the return status is `Z_OK'. When the return status is `Z_STREAM_END' the `$buffer' parameter will contains what (if anything) was stored in the input buffer after the deflated data stream. This feature is useful when processing a file format that encapsulates a compressed data stream (e.g. gzip, zip). *$i->dict_adler()* ------------------ Returns the adler32 value for the dictionary. Example ------- Here is an example of using *inflate*. use strict ; use warnings ; use Compress::Zlib ; my $x = inflateInit() or die "Cannot create a inflation stream\n" ; my $input = '' ; binmode STDIN; binmode STDOUT; my ($output, $status) ; while (read(STDIN, $input, 4096)) { ($output, $status) = $x->inflate(\$input) ; print $output if $status == Z_OK or $status == Z_STREAM_END ; last if $status != Z_OK ; } die "inflation failed\n" unless $status == Z_STREAM_END ; COMPRESS/UNCOMPRESS =================== Two high-level functions are provided by *zlib* to perform in-memory compression. They are compress and uncompress. Two Perl subs are provided which provide similar functionality. *$dest = compress($source) ;* Compresses *$source*. If successful it returns the compressed data. Otherwise it returns undef. The source buffer can either be a scalar or a scalar reference. *$dest = uncompress($source) ;* Uncompresses *$source*. If successful it returns the uncompressed data. Otherwise it returns undef. The source buffer can either be a scalar or a scalar reference. GZIP INTERFACE ============== A number of functions are supplied in *zlib* for reading and writing *gzip* files. This module provides an interface to most of them. In general the interface provided by this module operates identically to the functions provided by *zlib*. Any differences are explained below. *$gz = gzopen(filename or filehandle, mode)* This function operates identically to the *zlib* equivalent except that it returns an object which is used to access the other *gzip* methods. As with the *zlib* equivalent, the mode parameter is used to specify both whether the file is opened for reading or writing and to optionally specify a a compression level. Refer to the *zlib* documentation for the exact format of the mode parameter. If a reference to an open filehandle is passed in place of the filename, gzdopen will be called behind the scenes. The third example at the end of this section, *gzstream*, uses this feature. *$bytesread = $gz->gzread($buffer [, $size]) ;* Reads $size bytes from the compressed file into *$buffer*. If $size is not specified, it will default to 4096. If the scalar *$buffer* is not large enough, it will be extended automatically. Returns the number of bytes actually read. On EOF it returns 0 and in the case of an error, -1. *$bytesread = $gz->gzreadline($line) ;* Reads the next line from the compressed file into *$line*. Returns the number of bytes actually read. On EOF it returns 0 and in the case of an error, -1. It is legal to intermix calls to *gzread* and *gzreadline*. At this time *gzreadline* ignores the variable $/ ($INPUT_RECORD_SEPARATOR or $RS when English is in use). The end of a line is denoted by the C character `'\n''. *$byteswritten = $gz->gzwrite($buffer) ;* Writes the contents of *$buffer* to the compressed file. Returns the number of bytes actually written, or 0 on error. *$status = $gz->gzflush($flush) ;* Flushes all pending output into the compressed file. Works identically to the *zlib* function it interfaces to. Note that the use of *gzflush* can degrade compression. Refer to the *zlib* documentation for the valid values of *$flush*. *$gz->gzclose* Closes the compressed file. Any pending data is flushed to the file before it is closed. *$gz->gzerror* Returns the *zlib* error message or number for the last operation associated with $gz. The return value will be the *zlib* error number when used in a numeric context and the *zlib* error message when used in a string context. The *zlib* error number constants, shown below, are available for use. Z_OK Z_STREAM_END Z_ERRNO Z_STREAM_ERROR Z_DATA_ERROR Z_MEM_ERROR Z_BUF_ERROR $gzerrno The $gzerrno scalar holds the error code associated with the most recent *gzip* routine. Note that unlike *gzerror()*, the error is not associated with a particular file. As with *gzerror()* it returns an error number in numeric context and an error message in string context. Unlike *gzerror()* though, the error message will correspond to the *zlib* message when the error is associated with *zlib* itself, or the UNIX error message when it is not (i.e. *zlib* returned `Z_ERRORNO'). As there is an overlap between the error numbers used by *zlib* and UNIX, $gzerrno should only be used to check for the presence of an error in numeric context. Use *gzerror()* to check for specific *zlib* errors. The *gzcat* example below shows how the variable can be used safely. Examples -------- Here is an example script which uses the interface. It implements a *gzcat* function. use strict ; use warnings ; use Compress::Zlib ; die "Usage: gzcat file...\n" unless @ARGV ; my $file ; foreach $file (@ARGV) { my $buffer ; my $gz = gzopen($file, "rb") or die "Cannot open $file: $gzerrno\n" ; print $buffer while $gz->gzread($buffer) > 0 ; die "Error reading from $file: $gzerrno" . ($gzerrno+0) . "\n" if $gzerrno != Z_STREAM_END ; $gz->gzclose() ; } Below is a script which makes use of *gzreadline*. It implements a very simple grep like script. use strict ; use warnings ; use Compress::Zlib ; die "Usage: gzgrep pattern file...\n" unless @ARGV >= 2; my $pattern = shift ; my $file ; foreach $file (@ARGV) { my $gz = gzopen($file, "rb") or die "Cannot open $file: $gzerrno\n" ; while ($gz->gzreadline($_) > 0) { print if /$pattern/ ; } die "Error reading from $file: $gzerrno\n" if $gzerrno != Z_STREAM_END ; $gz->gzclose() ; } This script, *gzstream*, does the opposite of the *gzcat* script above. It reads from standard input and writes a gzip file to standard output. use strict ; use warnings ; use Compress::Zlib ; binmode STDOUT; # gzopen only sets it on the fd my $gz = gzopen(\*STDOUT, "wb") or die "Cannot open stdout: $gzerrno\n" ; while (<>) { $gz->gzwrite($_) or die "error writing: $gzerrno\n" ; } $gz->gzclose ; Compress::Zlib::memGzip ----------------------- This function is used to create an in-memory gzip file. It creates a minimal gzip header. $dest = Compress::Zlib::memGzip($buffer) ; If successful, it returns the in-memory gzip file, otherwise it returns undef. The buffer parameter can either be a scalar or a scalar reference. Compress::Zlib::memGunzip ------------------------- This function is used to uncompress an in-memory gzip file. $dest = Compress::Zlib::memGunzip($buffer) ; If successful, it returns the uncompressed gzip file, otherwise it returns undef. The buffer parameter can either be a scalar or a scalar reference. The contents of the buffer parameter are destroyed after calling this function. CHECKSUM FUNCTIONS ================== Two functions are provided by *zlib* to calculate a checksum. For the Perl interface, the order of the two parameters in both functions has been reversed. This allows both running checksums and one off calculations to be done. $crc = adler32($buffer [,$crc]) ; $crc = crc32($buffer [,$crc]) ; The buffer parameters can either be a scalar or a scalar reference. If the $crc parameters is undef, the crc value will be reset. ACCESSING ZIP FILES =================== Although it is possible to use this module to access .zip files, there is a module on CPAN that will do all the hard work for you. Check out http://www.cpan.org/modules/by-module/Archive/Archive-Zip-*.tar.gz Assuming you don't want to use this module to access zip files there are a number of undocumented features in the zlib library you need to be aware of. 1. When calling *inflateInit* or *deflateInit* the *WindowBits* parameter must be set to `-MAX_WBITS'. This disables the creation of the zlib header. 2. The zlib function *inflate*, and so the *inflate* method supplied in this module, assume that there is at least one trailing byte after the compressed data stream. Normally this isn't a problem because both the gzip and zip file formats will guarantee that there is data directly after the compressed data stream. CONSTANTS ========= All the *zlib* constants are automatically imported when you make use of *Compress::Zlib*. AUTHOR ====== The *Compress::Zlib* module was written by Paul Marquess, `Paul.Marquess@btinternet.com'. The latest copy of the module can be found on CPAN in `modules/by-module/Compress/Compress-Zlib-x.x.tar.gz'. The primary site for the *zlib* compression library is `http://www.info-zip.org/pub/infozip/zlib/'. MODIFICATION HISTORY ==================== See the README file.