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

[kyoki at bestpractical.com]

Author: kyoki
Date: Wed Jul 30 11:30:49 2008
New Revision: 14635

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

Log:
 r30173 at nyx:  kyoki | 2008-07-30 11:30:43 -0400
 more documentation!


Modified: Data-Plist/lib/Data/Plist.pm
==============================================================================
--- Data-Plist/lib/Data/Plist.pm	(original)
+++ Data-Plist/lib/Data/Plist.pm	Wed Jul 30 11:30:49 2008
@@ -4,15 +4,36 @@
 
 =head1 SYNOPSIS
 
- #load
+ # Create a new plist containing $data
  my $plist = Data::Plist->new($data);
 
+ # Get nested arrays containing the perl data structure's
+ # information
+ my $ret = $plist->raw_data;
+
+ # Get perl data structure
+ $ret = $plist->data;
+
+ $ret = $plist->raw_object;
+
+ # Get an Objective C object
+ $ret = $plist->object;
+
+
 =head1 DESCRIPTION
 
 
 
 =head1 SERIALIZED DATA
 
+Perl data structures that have been serialized become
+nested array structures containing their data and their
+data type. Example:
+
+[ array => [ string => "kitten" ], [ integer => 42], [ real => 3.14159 ] ]
+
+Array references are passed around when dealing with
+serialized data.
 
 =head1 KEYED ARCHIVES
 
@@ -46,6 +67,13 @@
     return bless { data => undef, @_ } => $class;
 }
 
+=head2 collapse $data
+
+Takes an array of serialized data C<$data>. Recursively
+returns the actual data, without the datatype labels.
+
+=cut
+
 sub collapse {
     my $self = shift;
     my ($data) = @_;
@@ -71,7 +99,6 @@
         return $data->[1];
     }
 
-    return $data;
 }
 
 =head2 raw_data
@@ -125,6 +152,12 @@
     return 1;
 }
 
+=head2 unref
+
+Recursively strips references from the plist.
+
+=cut
+
 sub unref {
     my $self = shift;
     my $p    = shift;
@@ -182,6 +215,7 @@
 }
 
 sub _raw_object {
+
     my $self = shift;
     return unless $self->is_archive;
     return $self->unref( $self->raw_data->[1]{'$top'}[1]{root} );