File Coverage

blib/lib/Data/HexDump/Range.pm
Criterion Covered Total %
statement 60 82 73.1
branch 2 6 33.3
condition 3 3 100.0
subroutine 19 24 79.1
pod 6 6 100.0
total 90 121 74.3


line stmt bran cond sub pod time code
1              
2             package Data::HexDump::Range ;
3              
4 2     2   43021 use strict;
  2         2  
  2         44  
5 2     2   7 use warnings ;
  2         2  
  2         39  
6 2     2   8 use Carp ;
  2         9  
  2         137  
7              
8             BEGIN
9             {
10              
11 2         12 use Sub::Exporter -setup =>
12             {
13             exports => [ qw() ],
14             groups =>
15             {
16             all => [ qw() ],
17             }
18 2     2   918 };
  2         16773  
19            
20 2     2   533 use vars qw ($VERSION);
  2         2  
  2         72  
21 2     2   30 $VERSION = '0.13';
22             }
23              
24             #-------------------------------------------------------------------------------
25              
26 2     2   933 use English qw( -no_match_vars ) ;
  2         5875  
  2         8  
27              
28 2     2   1438 use Readonly ;
  2         5315  
  2         102  
29             Readonly my $EMPTY_STRING => q{} ;
30              
31 2     2   8 use Carp qw(carp croak confess) ;
  2         2  
  2         75  
32              
33 2     2   7 use List::Util qw(min max) ;
  2         1  
  2         177  
34 2     2   955 use List::MoreUtils qw(all) ;
  2         13646  
  2         9  
35 2     2   862 use Scalar::Util qw(looks_like_number) ;
  2         3  
  2         74  
36 2     2   1123 use Term::ANSIColor ;
  2         9466  
  2         105  
37 2     2   1206 use Data::TreeDumper ;
  2         33763  
  2         125  
38              
39 2     2   785 use Data::HexDump::Range::Object ;
  2         5  
  2         55  
40 2     2   775 use Data::HexDump::Range::Gather ;
  2         3  
  2         47  
41 2     2   857 use Data::HexDump::Range::Split ;
  2         3  
  2         56  
42 2     2   739 use Data::HexDump::Range::Format ;
  2         5  
  2         873  
43              
44             #-------------------------------------------------------------------------------
45              
46             =head1 NAME
47              
48             Data::HexDump::Range - Hexadecimal Range Dumper with color, bitfields and skip ranges
49              
50             =head1 SYNOPSIS
51              
52             my $hdr = Data::HexDump::Range->new() ;
53            
54             print $hdr->dump([['magic cookie', 12, 'red'],['image type', 2, 'green']], $data) ;
55             print $hdr->dump('magic cookie, 12, red :image type, 2, green', $data) ;
56            
57             $hdr->gather(['magic cookie', 12, 'red'], $data) ;
58             $hdr->gather(['image type', 2, 'green'], $other_data) ;
59            
60             print $hdr->dump_gathered() ;
61             $hdr->reset() ;
62              
63             =head1 DESCRIPTION
64              
65             Creates a dump from binary data and user defined I descriptions. The goal of this module is
66             to create an easy to understand dump of binary data.
67              
68             This achieved through:
69              
70             =over 2
71              
72             =item * Highlighted (colors) dump that is easier to understand than a monochrome blob of hex data
73              
74             =item * Multiple rendering modes with different output formats
75              
76             =item * Bitfield rendering
77              
78             =item * Skipping uninterresting data
79              
80             =item * The possibility to describe complex structures
81              
82             =back
83              
84             =head1 DOCUMENTATION
85              
86             The shortest perl dumper is C, courtesy of a golfing session
87             with Andrew Rodland aka I. I, I, I and other provided valuable insight particularely with the html output.
88              
89             B from libma L is nice tools that inspired me to write this module. This module offers many
90             more options but B may be a better alternative If you need very fast dump generation.
91              
92             B splits binary data according to user defined I and renderes them as a B or/and B data dump.
93             The data dump can be rendered in ANSI, ASCII or HTML.
94              
95             =head2 Rendered Columns
96              
97             You can choose which columns are rendered by setting options when creating a Data::HexDump::Range object.
98             The default rendering includes the following
99              
100             RANGE_NAME OFFSET CUMULATIVE_OFFSET HEX_DUMP ASCII_DUMP
101              
102             which corresponds to the object below:
103              
104             Data::HexDump::Range->new
105             (
106             FORMAT => 'ANSI',
107             COLOR => 'cycle',
108            
109             ORIENTATION => 'horizontal',
110            
111             DISPLAY_RANGE_NAME => 1 ,
112            
113             DISPLAY_OFFSET => 1 ,
114             OFFSET_FORMAT => 'hex',
115            
116             DISPLAY_HEX_DUMP => 1,
117             DISPLAY_ASCII_DUMP => 1,
118            
119             DATA_WIDTH => 16,
120             ) ;
121              
122             If you decided that you wanted the binary data to be showed in decimal instead for hexadecimal, you' set DISPLAY_HEX_DUMP => 0 and DISPLAY_DEC_DUMP => 1.
123             See L for all the possible options. Most option are also available from the command line utility I.
124              
125             =head2 Orientation
126              
127             The examples below show the output of the following command:
128              
129             $>hdr -r 'magic cookie,12:padding, 32:header,5:data, 20:extra data,#:header,5:data,40:footer,4' -col -o ver -display_ruler lib/Data/HexDump/Range.pm
130              
131             =head3 Vertical orientation
132              
133             In this orientation mode, each range displayed on a separate line.
134              
135             RANGE_NAME OFFSET CUMULATI HEX_DUMP ASCII_DUMP
136             0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789012345
137             magic cookie 00000000 00000000 0a 70 61 63 6b 61 67 65 20 44 61 74 .package Dat
138             padding 0000000c 00000000 61 3a 3a 48 a::H
139             padding 00000010 00000004 65 78 44 75 6d 70 3a 3a 52 61 6e 67 65 20 3b 0a exDump::Range ;.
140             padding 00000020 00000014 0a 75 73 65 20 73 74 72 69 63 74 3b .use strict;
141             header 0000002c 00000000 0a 75 73 65 .use
142             header 00000030 00000004 20
143             data 00000031 00000000 77 61 72 6e 69 6e 67 73 20 3b 0a 75 73 65 20 warnings ;.use
144             data 00000040 0000000f 43 61 72 70 20 Carp
145             "extra data"
146             header 00000045 00000000 3b 0a 0a 42 45 ;..BE
147             data 0000004a 00000000 47 49 4e 20 0a 7b GIN .{
148             data 00000050 00000006 0a 0a 75 73 65 20 53 75 62 3a 3a 45 78 70 6f 72 ..use Sub::Expor
149             data 00000060 00000016 74 65 72 20 2d 73 65 74 75 70 20 3d 3e 20 0a 09 ter -setup => ..
150             data 00000070 00000026 7b 0a {.
151             footer 00000072 00000000 09 65 78 70 .exp
152              
153             In colors:
154              
155             =begin html
156              
157            
 
158             RANGE_NAME OFFSET CUMULATI HEX_DUMP ASCII_DUMP
159             0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789012345
160             magic cookie 00000000 00000000 0a 70 61 63 6b 61 67 65 20 44 61 74 .package Dat
161             padding 0000000c 00000000 61 3a 3a 48 a::H
162             padding 00000010 00000004 65 78 44 75 6d 70 3a 3a 52 61 6e 67 65 20 3b 0a exDump::Range ;.
163             padding 00000020 00000014 0a 75 73 65 20 73 74 72 69 63 74 3b .use strict;
164             header 0000002c 00000000 0a 75 73 65 .use
165             header 00000030 00000004 20
166             data 00000031 00000000 77 61 72 6e 69 6e 67 73 20 3b 0a 75 73 65 20 warnings ;.use
167             data 00000040 0000000f 43 61 72 70 20 Carp
168             "extra data"
169             header 00000045 00000000 3b 0a 0a 42 45 ;..BE
170             data 0000004a 00000000 47 49 4e 20 0a 7b GIN .{
171             data 00000050 00000006 0a 0a 75 73 65 20 53 75 62 3a 3a 45 78 70 6f 72 ..use Sub::Expor
172             data 00000060 00000016 74 65 72 20 2d 73 65 74 75 70 20 3d 3e 20 0a 09 ter -setup => ..
173             data 00000070 00000026 7b 0a {.
174             footer 00000072 00000000 09 65 78 70 .exp
175            
176            
177              
178             =end html
179              
180             =head3 Horizontal orientation
181              
182             In this mode, the data are packed together in the dump
183              
184             OFFSET HEX_DUMP ASCII_DUMP RANGE_NAME
185             0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789012345
186             00000000 0a 70 61 63 6b 61 67 65 20 44 61 74 61 3a 3a 48 .package Data::H magic cookie, padding,
187             00000020 65 78 44 75 6d 70 3a 3a 52 61 6e 67 65 20 3b 0a exDump::Range ;. padding,
188             00000030 0a 75 73 65 20 73 74 72 69 63 74 3b 0a 75 73 65 .use strict;.use padding, header,
189             00000050 20 77 61 72 6e 69 6e 67 73 20 3b 0a 75 73 65 20 warnings ;.use header, data,
190             00000070 43 61 72 70 20 3b 0a 0a 42 45 47 49 4e 20 0a 7b Carp ;..BEGIN .{ data, "extra data", header, data,
191             000000a0 0a 0a 75 73 65 20 53 75 62 3a 3a 45 78 70 6f 72 ..use Sub::Expor data,
192             000000b0 74 65 72 20 2d 73 65 74 75 70 20 3d 3e 20 0a 09 ter -setup => .. data,
193             000000c0 7b 0a 09 65 78 70 {..exp data, footer,
194              
195             In colors:
196              
197             =begin html
198              
199            
 
200              
201             OFFSET HEX_DUMP ASCII_DUMP RANGE_NAME
202             0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789012345
203             00000000 0a 70 61 63 6b 61 67 65 20 44 61 74 61 3a 3a 48 .package Data::H magic cookie, padding,
204             00000020 65 78 44 75 6d 70 3a 3a 52 61 6e 67 65 20 3b 0a exDump::Range ;. padding,
205             00000030 0a 75 73 65 20 73 74 72 69 63 74 3b 0a 75 73 65 .use strict;.use padding, header,
206             00000050 20 77 61 72 6e 69 6e 67 73 20 3b 0a 75 73 65 20 warnings ;.use header, data,
207             00000070 43 61 72 70 20 3b 0a 0a 42 45 47 49 4e 20 0a 7b Carp ;..BEGIN .{ data, "extra data", header, data,
208             000000a0 0a 0a 75 73 65 20 53 75 62 3a 3a 45 78 70 6f 72 ..use Sub::Expor data,
209             000000b0 74 65 72 20 2d 73 65 74 75 70 20 3d 3e 20 0a 09 ter -setup => .. data,
210             000000c0 7b 0a 09 65 78 70 {..exp data, footer,
211              
212            
213              
214             =end html
215              
216             =head2 Range definition
217              
218             my $simple_range = ['magic cookie', 12, 'red'] ;
219            
220             Ranges are Array references containing two to four elements:
221              
222             =over 2
223              
224             =item * name - a string
225              
226             =item * size - an integer or a format - a string
227              
228             =item * color - a string or undef
229              
230             =item * user information - a very short string descibing the range or undef
231              
232             =back
233              
234             Any of the elements can be replaced by a subroutine reference. See L below.
235              
236             You can also pass the ranges as a string. The L command line range dumper that was installed by this module uses the string format.
237              
238             Example:
239              
240             $>hdr --col -display_ruler -o ver -r 'header,12:name,10:magic,2:offset,4:BITMAP,4,bright_yellow:ff,x2b2:fx,b32:f0,b16:field,x8b8:field2, b17:footer,20' my_binary
241              
242             =head3 Size field format
243              
244             The size field is used to defined if the range is a normal range, a comment, a bitfield or a skip range. The formats are a s follows:
245              
246             format range example
247            
248             normal range => integer header, 4, bright_blue
249             comment => # data section start, #
250             extra header => @ header, @, red
251             bitfield => [XInteger][xInteger]bInteger bitfield, X2x4b4 # X is byte offset, x is bit offset
252             skip range => xInteger boring, X256,, comment
253              
254             Note that the integer part can be a hexadecimal value starting with I<0x>
255              
256             =head3 Coloring
257              
258             Ranges and ranges names are displayed according to the color field in the range definition.
259              
260             The color definition is one of:
261              
262             =over 2
263              
264             =item * A user defined color name found in B (see L)
265              
266             =item * An ansi color definition - 'blue on_yellow'
267              
268             =item * undef - will be repaced by a white color or picked from a cyclic color list (see B in L).
269              
270             =back
271              
272             =head3 Linear ranges
273              
274             For simple data formats, your can put all the your range descriptions in a array:
275              
276             my $image_ranges =
277             [
278             ['magic cookie', 12, 'red'],
279             ['size', 10, 'yellow'],
280             ['data', 10, 'blue on_yellow'],
281             ['timestamp', 5, 'green'],
282             ] ;
283              
284             =head3 Structured Ranges
285              
286             my $data_range = # definition to re-use
287             [
288             ['data header', 5, 'blue on_yellow'],
289             ['data', 100, 'blue'],
290             ] ;
291            
292             my $structured_range =
293             [
294             [
295             ['magic cookie', 12, 'red'],
296             ['padding', 88, 'yellow'],
297             $data_range,
298             ],
299            
300             [
301             ['extra data', 12, undef],
302             [
303             $data_range,
304             ['footer', 4, 'yellow on_red'],
305             ]
306             ],
307             ]
308              
309             =head4 Comment ranges
310              
311             If the size of a range is the string '#', the whole range is considered a comment
312              
313             my $range_defintion_with_comments =
314             [
315             ['comment text', '#', 'optional color for meta range'],
316             ['magic cookie', 12, 'red'],
317             ['padding', 88, 'yellow'],
318            
319             [
320             ['another comment', '#'],
321             ['data header', 5, 'blue on_yellow'],
322             ['data', 100, 'blue'],
323             ],
324             ] ;
325              
326             =head4 Extra header
327              
328             If the size of a range is the string '@', and extra header is inserted in the output. This is useful when
329             you have very long output and want an extra header.
330              
331             =head3 Bitfields
332              
333             Bitfields can be up to 32 bits long and can overlap each other. Bitfields are applied on the previously defined range.
334              
335             In the example below, bitfields I are extracted form the data defined by the I range.
336              
337             .------------. .--------------.
338             .---. | data range | | data hexdump |
339             | b | '------------' '--------------'
340             | i | | |
341             | t | BITMAP <----' 00000000 00000000 0a 70 61 63 <--' .pac
342             | f | ^ .ff 02 .. 03 -- -- -- 00 ----------------------------00-- .bitfield: ---.
343             | i |---> .fx 00 .. 31 0a 70 61 63 00001010011100000110000101100011 .bitfield: .pac
344             | e | v .f0 00 .. 15 -- -- 61 63 ----------------0110000101100011 .bitfield: --ac
345             | l | ^ ^ ^ ^
346             | d | | | | |
347             | s | .----------------------.-------------------.----------------------. .---------------------.
348             '---' | start bit .. end bit | bitfields hexdump | bitfield binary dump | | bitfield ascci dump |
349             '----------------------'-------------------'----------------------' '---------------------'
350              
351             The the format definiton is: an optional "x (for offset) + offset" + "b (for bits) + number of bits". Eg: I second byte in MYDATA.
352              
353             An example output containing normal data and bifields dumps using the comand below.
354              
355             $>hdr -r 'header,12:BITMAP,4,bright_yellow:ff,x2b2:fx,b32:f0,b16:footer,16' -o ver file_name
356              
357             =begin html
358              
359            
 
360             header 00000000 00000000 44 61 74 61 3a 3a 48 65 78 44 75 6d Data::HexDum
361             BITMAP 0000000c 00000000 70 3a 3a 52 p::R
362             .ff 02 .. 03 -- -- -- 00 ----------------------------00-- .bitfield: ---.
363             .fx 00 .. 31 70 3a 3a 52 01110000001110100011101001010010 .bitfield: p::R
364             .f0 00 .. 15 -- -- 3a 52 ----------------0011101001010010 .bitfield: --:R
365             footer 00000010 00000000 61 6e 67 65 0a 3d 3d 3d 3d 3d 3d 3d 3d 3d 3d 3d ange.===========
366            
367            
368              
369             =end html
370              
371             By default bitfields are not displayed in horizontal mode.
372              
373             =head3 Skip ranges
374              
375             If the size format is 'X' + number, that number of bytes is skipped from the data. B
376             will display the skip range in the dump but not the data.
377              
378             In the command below, the range 'skip' removes 32 bytes from the display. '>>' is prepended to the range name.
379              
380             Command: I
381              
382             RANGE_NAME OFFSET CUMULATI HEX_DUMP ASCII_DUMP
383             0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789012345
384             magic cookie 00000000 00000000 44 61 74 61 3a Data:
385             other 00000005 00000000 3a 48 65 78 44 75 6d 70 3a 3a 52 :HexDump::R
386             other 00000010 0000000b 61 6e 67 65 0a 3d 3d 3d 3d 3d 3d 3d 3d 3d 3d 3d ange.===========
387             other 00000020 0000001b 3d 3d 3d 3d 3d 3d 3d 3d 3d 0a =========.
388             .bf 00 .. 07 -- -- -- 0a ------------------------00001010 .bitfield: ---.
389             >>skip 0000002a 00000049 00 00 00 20 bytes skipped
390             more 0000004a 00000000 20 63 6f 6c 6f 72 color
391             more 00000050 00000006 2c 20 62 69 74 66 69 65 6c 64 73 20 61 6e , bitfields an
392              
393             in color:
394              
395             =begin html
396              
397            
 
398             RANGE_NAME OFFSET CUMULATI HEX_DUMP ASCII_DUMP
399             0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789012345
400             magic cookie 00000000 00000000 44 61 74 61 3a Data:
401             other 00000005 00000000 3a 48 65 78 44 75 6d 70 3a 3a 52 :HexDump::R
402             other 00000010 0000000b 61 6e 67 65 0a 3d 3d 3d 3d 3d 3d 3d 3d 3d 3d 3d ange.===========
403             other 00000020 0000001b 3d 3d 3d 3d 3d 3d 3d 3d 3d 0a =========.
404             .bf 00 .. 07 -- -- -- 0a ------------------------00001010 .bitfield: ---.
405             >>skip 0000002a 00000049 00 00 00 20 bytes skipped
406             more 0000004a 00000000 20 63 6f 6c 6f 72 color
407             more 00000050 00000006 2c 20 62 69 74 66 69 65 6c 64 73 20 61 6e , bitfields an
408            
409            
410              
411             =end html
412              
413             =head3 Dynamic range definition
414              
415             The whole range can be replaced by a subroutine reference or elements of the range can be replaced by
416             a subroutine definition.
417              
418             my $dynamic_range =
419             [
420             [\&name, \&size, \&color, \&comment ],
421             [\&define_range] # returns a range definition
422             ] ;
423              
424             =head4 'name' sub ref
425              
426             sub cloth_size
427             {
428             my ($self, $data, $used_data, $size, $range) = @_ ;
429             my %types = (O => 'S', 1 => 'M', 2 => 'L',) ;
430             return 'size:' . ($types{$data} // '?') ;
431             }
432            
433             $hdr->dump([\&cloth_size, 1, 'yellow'], $data) ;
434              
435             =head4 'size' sub ref
436              
437             sub cloth_size
438             {
439             my ($self, $data, $used_data, $size, $range) = @_ ;
440             return unpack "a", $data ;
441             }
442            
443             $hdr->dump(['data', \&get_size, 'yellow'], $data) ;
444              
445             =head4 'color' sub ref
446              
447             my $flip_flop = 1 ;
448             my @colors = ('green', 'red') ;
449            
450             sub alternate_color {$flip_flop ^= 1 ; return $colors[$flip_flop] }
451            
452             $hdr->dump(['data', 100, \&alternate_color], $data) ;
453              
454             =head4 'range' sub ref
455              
456             sub define_range(['whole range', 5, 'on_yellow']}
457            
458             $hdr->dump([\&define_range], $data) ;
459              
460              
461             =head2 define_range($data, $offset)
462              
463             Returns a range description for the next range to dump
464              
465             I - See L
466              
467             =over 2
468              
469             =item * $self - A Data::HexDump::Range object
470              
471             =item * $data - Binary string - the data passed to the I method
472              
473             =item * $offset - Integer - current offset in $data
474              
475             =back
476              
477             I -
478              
479             =over 2
480              
481             =item * $range - An array reference containing a name, size and color and user_information
482              
483             OR
484              
485             =item * undef - Ignore this range
486              
487             =item * $comment - String - an optional comment that will be displayed if DUMP_RANGE_DESCRIPTION is set.
488              
489             =back
490              
491             =head4
492              
493             B this is, very, different from L below.
494            
495             =head3 User defined range generator
496              
497             A subroutine reference can be passed as a range definition. The subroutine will be called repetitively
498             till the data is exhausted or the subroutine returns I.
499              
500             sub my_parser
501             {
502             my ($data, $offset) = @_ ;
503            
504             my $first_byte = unpack ("x$offset C", $data) ;
505            
506             $offset < length($data)
507             ? $first_byte == ord(0)
508             ? ['from odd', 5, 'blue on_yellow']
509             : ['from even', 3, 'green']
510             : undef ;
511             }
512            
513             my $hdr = Data::HexDump::Range->new() ;
514             print $hdr->dump(\&my_parser, '01' x 50) ;
515              
516             =head2 my_parser($data, $offset)
517              
518             Returns a range description for the next range to dump
519              
520             I - See L
521              
522             =over 2
523              
524             =item * $self - A Data::HexDump::Range object
525              
526             =item * $data - Binary string - the data passed to the I method
527              
528             =item * $offset - Integer - current offset in $data
529              
530             =back
531              
532             I -
533              
534             =over 2
535              
536             =item * $range - An array reference containing a name, size and color
537              
538             OR
539              
540             =item * undef - Done parsing
541              
542             =back
543              
544             =cut
545              
546             =head1 EXAMPLES
547              
548             See L in the distribution.
549              
550             =head1 SUBROUTINES/METHODS
551              
552             =cut
553              
554             #-------------------------------------------------------------------------------
555              
556             sub new
557             {
558              
559             =head2 new(NAMED_ARGUMENTS)
560              
561             Create a Data::HexDump::Range object.
562              
563             my $hdr = Data::HexDump::Range->new() ; # use default setup
564            
565             my $hdr = Data::HexDump::Range->new
566             (
567             FORMAT => 'ANSI'|'ASCII'|'HTML',
568             COLOR => 'bw' | 'cycle',
569             OFFSET_FORMAT => 'hex' | 'dec',
570             DATA_WIDTH => 16 | 20 | ... ,
571             DISPLAY_RANGE_NAME => 1 ,
572             MAXIMUM_RANGE_NAME_SIZE => 16,
573             DISPLAY_COLUMN_NAMES => 0,
574             DISPLAY_RULER => 0,
575             DISPLAY_OFFSET => 1 ,
576             DISPLAY_CUMULATIVE_OFFSET => 1 ,
577             DISPLAY_ZERO_SIZE_RANGE_WARNING => 1,
578             DISPLAY_ZERO_SIZE_RANGE => 1,
579             DISPLAY_RANGE_SIZE => 1,
580             DISPLAY_ASCII_DUMP => 1 ,
581             DISPLAY_HEX_DUMP => 1,
582             DISPLAY_HEXASCII_DUMP => 0,
583             DISPLAY_DEC_DUMP => 0,
584             COLOR_NAMES => {},
585             ORIENTATION => 'horizontal',
586             ) ;
587              
588             I - All arguments are optional. Default values are listed below.
589              
590             =over 2
591              
592             =item * NAME - String - Name of the Data::HexDump::Range object, set to 'Anonymous' by default
593              
594             =item * INTERACTION - Hash reference - Set of subs that are used to display information to the user
595              
596             Useful if you use Data::HexDump::Range in an application without terminal.
597              
598             =item * VERBOSE - Boolean - Display information about the creation of the object. Default is I
599              
600             =item * DUMP_ORIGINAL_RANGE_DESCRIPTION - Boolean - Diplays the un-processed range descritption.
601              
602             With B, this fields can be used to peek into what range descriptions the module get and how they are
603             transformed into the format that is internally used by the module. These are for debugging purpose and you should normally not need to used them.
604              
605             Original range description
606             |- 0 = 'Data'
607             |- 1 = '128'
608             |- 2 = undef
609             `- 3 = undef
610            
611             Original range description
612             |- 0 = CODE(0x1dc5230)
613             |- 1 = undef
614             |- 2 = undef
615             `- 3 = undef
616              
617             =item * DUMP_RANGE_DESCRIPTION - Boolean - Diplays the processed range descritption in plain text before the dump
618              
619             128->26:Data
620             |- COLOR = undef
621             |- DATA = '_blah_blah_blah_blah_blah[\n]'
622             |- IS_BITFIELD = '0'
623             |- IS_COMMENT = '0'
624             |- IS_SKIP = '0'
625             |- NAME = '128->26:Data'
626             |- OFFSET = '20'
627             |- unpack format = 'x20 a26'
628             `- USER_INFORMATION = undef
629              
630             =item * FORMAT - String - format of the dump string generated by Data::HexDump::Range.
631              
632             Default is B which allows for colors. Other formats are 'ASCII' and 'HTML'.
633              
634             =item * COLOR - String 'cycle', 'no_cycle', 'bw'
635              
636             Controls the coloring policy of ranges
637              
638             =over 2
639              
640             =item * cycle: if the range definition contains a color does not define a color, a color is automatically assigned
641              
642             =item * no_cycle: only ranges with a color defined are colorized
643              
644             =item * bw: no color is used even if the range contains a color definition
645              
646             =back
647              
648             =item * OFFSET_FORMAT - String - 'hex' or 'dec'
649              
650             If set to 'hex', the offset will be displayed in base 16. When set to 'dec' the offset is displayed
651             in base 10. Default is 'hex'.
652              
653             =item * DATA_WIDTH - Integer - Number of elements displayed per line. Default is 16.
654              
655             =item * DISPLAY_RANGE_NAME - Boolean - If set, range names are displayed in the dump.
656              
657             =item * MAXIMUM_RANGE_NAME_SIZE - Integer - maximum size of a range name (horizontal mode). Default size is 16.
658              
659             =item * DISPLAY_COLUMN_NAMES - Boolean - If set, the column names are displayed. Default I
660              
661             =item * DISPLAY_RULER - Boolean - if set, a ruler is displayed above the dump, Default is I
662              
663             =item * DISPLAY_OFFSET - Boolean - If set, the offset column is displayed. Default I
664              
665             =item * DISPLAY_CUMULATIVE_OFFSET - Boolean - If set, the cumulative offset column is displayed in 'vertical' rendering mode. Default is I
666              
667             =item * OFFSET_START - Integer - value added to the offset.
668              
669             =item * DISPLAY_ZERO_SIZE_RANGE - Boolean - if set, ranges that do not consume data are displayed. default is I
670              
671             =item * DISPLAY_ZERO_SIZE_RANGE_WARNING - Boolean - if set, a warning is emitted if ranges that do not consume data. Default is I
672              
673             =item * DISPLAY_COMMENT_RANGE - Boolean - if set, comment ranges are displayed. default is I
674              
675             =item * DISPLAY_RANGE_SIZE - Bolean - if set the range size is prepended to the name. Default I
676              
677             =item * DISPLAY_ASCII_DUMP - Boolean - If set, the ASCII representation of the binary data is displayed. Default is I
678              
679             =item * DISPLAY_HEX_DUMP - Boolean - If set, the hexadecimal dump column is displayed. Default is I
680              
681             =item * DISPLAY_HEXASCII_DUMP - Boolean - If set, the comined hexadecimal and ASCII dump column is displayed. Default is I
682              
683             =item * DISPLAY_DEC_DUMP - Boolean - If set, the decimall dump column is displayed. Default is I
684              
685             =item * DISPLAY_BITFIELD_SOURCE - Boolean - if set an extra column indicating the source of bitfields is displayed
686              
687             =item * MAXIMUM_BITFIELD_SOURCE_SIZE - Integer - maximum size of the bifield source column
688              
689             =item * DISPLAY_USER_INFORMATION - Boolean - if set an extra column displaying user supplied information is shown
690              
691             =item * MAXIMUM_USER_INFORMATION_SIZE - Integer - maximum size of theuser information column
692              
693             =item * DISPLAY_BITFIELDS - Boolean - if set the bitfields are displayed
694              
695             =item * BIT_ZERO_ON_LEFT - Boolean - if set the bit of index 0 is on left growing to the right. Default I
696              
697             =item * COLOR_NAMES - A hash reference
698              
699             {
700             ANSI =>
701             {
702             header => 'yellow on_blue',
703             data => 'yellow on_black',
704             },
705            
706             HTML =>
707             {
708             header => 'FFFF00 0000FF',
709             data => 'FFFF00 000000',
710             },
711             }
712              
713             =item * ORIENTATION - String - 'vertical' or 'horizontal' (the default).
714              
715             =back
716              
717             I - Nothing
718              
719             I - Dies if an unsupported option is passed.
720              
721             =cut
722              
723 3     3 1 1119 my ($invocant, @setup_data) = @_ ;
724              
725 3   100     11 my $class = ref($invocant) || $invocant ;
726 3 100       21 confess 'Error: Invalid constructor call' unless defined $class ;
727              
728 2         2 my $object = {} ;
729              
730 2         5 my ($package, $file_name, $line) = caller() ;
731 2         27 bless $object, $class ;
732              
733 2         10 $object->Setup($package, $file_name, $line, @setup_data) ;
734              
735 2         4 return($object) ;
736             }
737              
738             #-------------------------------------------------------------------------------
739              
740             sub gather
741             {
742              
743             =head2 gather($range_description, $data, $offset, $size)
744              
745             Dump the data, up to $size, according to the description. The data dump is kept in the object so you can
746             merge multiple gathered dumps and get a single rendering.
747              
748             $hdr->gather($range_description, $data, $offset, $size)
749             $hdr->gather($range_description, $more_data)
750            
751             print $hdr->dump_gathered() ;
752              
753             I
754              
755             =over 2
756              
757             =item * $range_description - See L
758            
759             =item * $data - A string - binary data to dump
760              
761             =item * $offset - dump data from offset
762              
763             =over 2
764              
765             =item * undef - start from first byte
766              
767             =back
768              
769             =item * $size - amount of data to dump
770              
771             =over 2
772              
773             =item * undef - use range description
774              
775             =item * CONSUME_ALL_DATA - apply range descritption till all data is consumed
776              
777             =back
778              
779             =back
780              
781             I - An integer - the number of processed bytes
782              
783             I - See L<_gather>
784              
785             =cut
786              
787 0     0 1   my ($self, $range, $data, $offset, $size) = @_ ;
788              
789 0           my ($gathered_data, $used_data) = $self->_gather($self->{GATHERED}, $range, $data, $offset, $size) ;
790              
791 0           return $used_data ;
792             }
793              
794             #-------------------------------------------------------------------------------
795              
796             sub dump_gathered
797             {
798              
799             =head2 dump_gathered()
800              
801             Returns the dump string for the gathered data.
802              
803             $hdr->gather($range_description, $data, $size)
804             $hdr->gather($range_description, $data, $size)
805            
806             print $hdr->dump_gathered() ;
807              
808             I - None
809              
810             I - A string - the binary data formated according to the rnage descriptions
811              
812             I - None
813              
814             =cut
815              
816 0     0 1   my ($self) = @_ ;
817              
818 0           my $split_data = $self->split($self->{GATHERED}) ;
819              
820 0           $self->add_information($split_data) ;
821              
822 0           return $self->format($split_data) ;
823             }
824              
825             #-------------------------------------------------------------------------------
826              
827             sub dump ## no critic (Subroutines::ProhibitBuiltinHomonyms)
828             {
829              
830             =head2 dump($range_description, $data, $offset, $size)
831              
832             Dump the data, up to $size, according to the description
833              
834             I - See L
835              
836             I - A string - the formated dump
837              
838             I - dies if the range description is invalid
839              
840             =cut
841              
842 0     0 1   my ($self, $range_description, $data, $offset, $size) = @_ ;
843              
844 0 0         return unless defined wantarray ;
845              
846 0           local $self->{GATHERED} = [] ;
847              
848 0           my ($gathered_data, $used_data) = $self->_gather($self->{GATHERED}, $range_description, $data, $offset, $size) ;
849              
850 0           my $split_data = $self->split($gathered_data) ;
851              
852 0           $self->add_information($split_data) ;
853              
854 0           return $self->format($split_data) ;
855             }
856              
857             #-------------------------------------------------------------------------------
858              
859             sub get_dump_and_consumed_data_size
860             {
861              
862             =head2 get_dump_and_consumed_data_size($range_description, $data, $offset, $size)
863              
864             Dump the data, from $offset up to $size, according to the $range_description
865              
866             I - See L
867              
868             I -
869              
870             =over 2
871              
872             =item * A string - the formated dump
873              
874             =item * An integer - the number of bytes consumed by the range specification
875              
876             =back
877              
878             I - dies if the range description is invalid
879              
880             =cut
881              
882 0     0 1   my ($self,$data, $offset, $size) = @_ ;
883              
884 0 0         return unless defined wantarray ;
885              
886 0           my ($gathered_data, $used_data) = $self->_gather(undef, $data, $offset, $size) ;
887              
888 0           my $dump =$self->format($self->split($gathered_data)) ;
889              
890 0           return $dump, $used_data ;
891             }
892              
893             #-------------------------------------------------------------------------------
894              
895             sub reset ## no critic (Subroutines::ProhibitBuiltinHomonyms)
896             {
897              
898             =head2 reset()
899              
900             Clear the gathered dump
901              
902             I - None
903              
904             I - Nothing
905              
906             I - None
907              
908             =cut
909              
910 0     0 1   my ($self) = @_ ;
911              
912 0           $self->{GATHERED} = [] ;
913              
914 0           return ;
915             }
916              
917             #-------------------------------------------------------------------------------
918              
919             1 ;
920              
921             =head1 BUGS AND LIMITATIONS
922              
923             None so far.
924              
925             =head1 AUTHOR
926              
927             Nadim ibn hamouda el Khemir
928             CPAN ID: NKH
929             mailto: nadim@cpan.org
930              
931             =head1 COPYRIGHT AND LICENSE
932              
933             Copyright Nadim Khemir 2010-2012.
934              
935             This program is free software; you can redistribute it and/or
936             modify it under the terms of either:
937              
938             =over 4
939              
940             =item * the GNU General Public License as published by the Free
941             Software Foundation; either version 1, or (at your option) any
942             later version, or
943              
944             =item * the Artistic License version 2.0.
945              
946             =back
947              
948             =head1 SUPPORT
949              
950             You can find documentation for this module with the perldoc command.
951              
952             perldoc Data::HexDump::Range
953              
954             You can also look for information at:
955              
956             =over 4
957              
958             =item * AnnoCPAN: Annotated CPAN documentation
959              
960             L
961              
962             =item * RT: CPAN's request tracker
963              
964             Please report any bugs or feature requests to L .
965              
966             We will be notified, and then you'll automatically be notified of progress on
967             your bug as we make changes.
968              
969             =item * Search CPAN
970              
971             L
972              
973             =back
974              
975             =head1 SEE ALSO
976              
977             L, L, L, L
978              
979             =cut