From aac9f02cab2d03379669c2f278d62330151d44e0 Mon Sep 17 00:00:00 2001
From: Mischa Poslawsky <wormy@shiar.org>
Date: Tue, 3 Mar 2009 15:00:55 +0100
Subject: [PATCH] document Parse::Binary::Nested features

Describe the differences with CORE::unpack(), since it's growing into
a superset basically.
---
 Parse/Binary/Nested.pm | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/Parse/Binary/Nested.pm b/Parse/Binary/Nested.pm
index e4cacc3..9bac394 100644
--- a/Parse/Binary/Nested.pm
+++ b/Parse/Binary/Nested.pm
@@ -87,6 +87,38 @@ Parse::Binary::Nested - Structured unpack
 
 =head1 DESCRIPTION
 
+Converts a string into a hash of values, just like C<unpack>
+except that it allows you to name and nest the resulting elements.
+
+Format declarations are simalar to C<pack> templates,
+with the following additions:
+
+=over
+
+=item *
+
+An array ref groups additional declarations,
+with the first value specifying a repetition.  If this count is variable,
+the resulting value will be an array ref of hashes.
+
+	repeat => ['C', name => 'a*', value => 'S']
+
+With a count of 1, it will return only a hash ref,
+thereby simply grouping declarations:
+
+	test_foo => 'C'
+	test => [1, foo => 'C']
+
+=item *
+
+A template value of C<Ca$length> is recognised as a length-preceded string
+with a constant (maximal) size, and will return only the string adjusted
+to its length.
+This behaviour is very similar to C<(C/a@x$length)>, except that it never reads
+more than the given number of bytes.
+
+=back
+
 =head1 AUTHOR
 
 Mischa POSLAWSKY <perl@shiar.org>
-- 
2.30.0