NAME

    IO::Handle::Packable - add pack and unpack methods to an IO::Handle

SYNOPSIS

       use IO::Handle::Packable;
    
       my $fh = IO::Handle::Packable->new;
       $fh->open( "my-data.dat", ">" );
    
       while( my ( $x, $y, $value ) = $fh->unpack( "S S i" ) ) {
          print "Value at ($x,$y) is $value\n";
       }

DESCRIPTION

    This subclass of IO::File adds two new methods to an IO handle; "pack"
    and "unpack". These provide the ability to write or read packed binary
    values to and from the filehandle, using the same kind of format
    strings as the core perl functions of the same names.

 Unpack Format

    Note that due to limitations in the way core perl's unpack() function
    works, this module has to know in advance how many bytes will be needed
    per read() call, before it can unpack the data. As a result, it cannot
    cope with all of the features that core's unpack() can do.

    The following features are supported:

       a A                  # binary and ASCII data of fixed length
    
       c C s S i I l L q Q  # integers
    
       n N v V              # legacy fixed-endian integers
    
       f d                  # native floating-point
    
       s< s>                # endian specifiers
    
       a123  i45            # repeat counts

    The following features are not currently supported, though should be
    relatively easy to add:

       b B                  # bitstrings
    
       F D                  # perl-internal floating-point
    
       i!                   # native-length integers
    
       (c c s)              # groups
    
       #                    # comments

    Due to needing to know lengths in advance, the following features will
    be much harder to implement without at least some redesign to the
    current implementation:

       z*                   # NUL-terminated ASCIIZ strings
    
       n/A                  # length-prefixed strings
    
       . @ x                # positioning control

METHODS

 pack

       $fh->pack( $format, @values )

    Uses the core pack function to pack the values given the format into a
    binary string, then writes the result to the filehandle.

 unpack

       @values = $fh->unpack( $format )

    Uses the core unpack function to unpack bytes read from the filehandle
    using the given format.

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>

