[Bps-public-commit] r14591 - in Data-Plist: .

[kyoki at bestpractical.com]

Author: kyoki
Date: Tue Jul 29 11:23:54 2008
New Revision: 14591

Modified:
   Data-Plist/   (props changed)
   Data-Plist/lib/Data/Plist/BinaryReader.pm

Log:
 r30124 at nyx:  kyoki | 2008-07-29 11:23:51 -0400
 rest of BinaryReader documentation. probably needs content and grammar proofing since I haven't actually slept...


Modified: Data-Plist/lib/Data/Plist/BinaryReader.pm
==============================================================================
--- Data-Plist/lib/Data/Plist/BinaryReader.pm	(original)
+++ Data-Plist/lib/Data/Plist/BinaryReader.pm	Tue Jul 29 11:23:54 2008
@@ -15,7 +15,9 @@
 
 =head1 DESCRIPTION
 
-C<Data::Plist::BinaryReader>
+C<Data::Plist::BinaryReader> takes data formatted as one of
+Apple's binary property lists, either from a string or a
+filehandle and returns it as a C<Data::Plist>.
 
 =cut
 
@@ -292,6 +294,16 @@
     return [ UID => $v ];
 }
 
+=head2 binary_read $objNum
+
+Takes an integer indicating the offset number of the
+current object C<$objNum> and checks to make sure it's
+valid. Reads the object's type and size and then matches
+the type to its read method. Passes the size to the correct
+method and returns what that method returns.
+
+=cut
+
 sub binary_read {
     my $self = shift;
     my ($objNum) = @_;
@@ -336,7 +348,9 @@
 Takes a string of binary information in Apple's binary
 property list format C<$string>. Checks to ensure that it's
 of the correct format and then passes its superclass's
-L</open_string>.
+L</open_string>. The error proofing is done because
+seeking in in-memory filehandles can cause perl 5.8.8 to
+explode with "Out of memory" or "panic: memory wrap".
 
 =cut
 
@@ -344,9 +358,6 @@
     my $self = shift;
     my ($str) = @_;
 
-    # Seeking in in-memory filehandles can cause perl 5.8.8 to explode
-    # with "Out of memory" or "panic: memory wrap"; Do some
-    # error-proofing here.
     die "Not a binary plist file\n"
         unless length $str >= 8 and substr( $str, 0, 8 ) eq "bplist00";
     die "Read of plist trailer failed\n"
@@ -357,6 +368,17 @@
     return $self->SUPER::open_string($str);
 }
 
+=head2 open_fh $filehandle
+
+Used for reading binary data from a filehandle
+C<$filehandle> rather than a string. Opens the filehandle
+and sanity checks the header, trailer and offset
+table. Returns a C<Data::Plist> containing the top object
+of the filehandle after it's been passed to
+L</binary_read>.
+
+=cut
+
 sub open_fh {
     my $self = shift;
     $self = $self->new() unless ref $self;