Range.pm

filter: Statementstmt 73.8% 62 / 84 Branchbran 33.3% 2 / 6 Conditioncond 100% 3 / 3 MC/DCmcdc 100% 2 / 2 Subroutinesub 79.1% 19 / 24 Podpod 100% 6 / 6 totaltotal 75.2% 94 / 125 CC 5 SCAR 7.1
CC
5
Cov
72%
dump
6.0
get_dump_and_consumed_data_size
6.0
new
3.0
CRAP 2.0
« Range/Format.pm ↑ Summary
1  
2 package Data::HexDump::Range ;
3  
4 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 2 ▶use warnings ;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 2 ▶use Carp ;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 BEGIN
9 2 ▶{
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 2 ▶use Sub::Exporter -setup =>
Subroutine BEGIN: called CC=1 SCAR=0.0
12 {
13 exports => [ qw() ],
14 groups =>
15 {
16 all => [ qw() ],
17 }
18 2 };
19
20 2 ▶use vars qw ($VERSION);
Subroutine BEGIN: called CC=1 SCAR=0.0
21 2 $VERSION = '0.13';
22 }
23  
24 #-------------------------------------------------------------------------------
25  
26 2 ▶use English qw( -no_match_vars ) ;
Subroutine BEGIN: called CC=1 SCAR=0.0
27  
28 2 ▶use Readonly ;
Subroutine BEGIN: called CC=1 SCAR=0.0
29 2 Readonly my $EMPTY_STRING => q{} ;
30  
31 2 ▶use Carp qw(carp croak confess) ;
Subroutine BEGIN: called CC=1 SCAR=0.0
32  
33 2 ▶use List::Util qw(min max) ;
Subroutine BEGIN: called CC=1 SCAR=0.0
34 2 ▶use List::MoreUtils qw(all) ;
Subroutine BEGIN: called CC=1 SCAR=0.0
35 2 ▶use Scalar::Util qw(looks_like_number) ;
Subroutine BEGIN: called CC=1 SCAR=0.0
36 2 ▶use Term::ANSIColor ;
Subroutine BEGIN: called CC=1 SCAR=0.0
37 2 ▶use Data::TreeDumper ;
Subroutine BEGIN: called CC=1 SCAR=0.0
38  
39 2 ▶use Data::HexDump::Range::Object ;
Subroutine BEGIN: called CC=1 SCAR=0.0
40 2 ▶use Data::HexDump::Range::Gather ;
Subroutine BEGIN: called CC=1 SCAR=0.0
41 2 ▶use Data::HexDump::Range::Split ;
Subroutine BEGIN: called CC=1 SCAR=0.0
42 2 ▶use Data::HexDump::Range::Format ;
Subroutine BEGIN: called CC=1 SCAR=0.0
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<range> 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<perl -ne 'BEGIN{$/=\16} printf "%07x0: @{[unpack q{(H2)*}]}\n", $.-1'>, courtesy of a golfing session
87 with Andrew Rodland <arodland@cpan.org> aka I<hobbs>. I<priodev>, I<tm604>, I<Khisanth> and other provided valuable insight particularely with the html output.
88  
89 B<hexd> from libma L<http://www.ioplex.com/~miallen/libmba/> is nice tools that inspired me to write this module. This module offers many
90 more options but B<hexd> may be a better alternative If you need very fast dump generation.
91  
92 B<Data::HexDump::Range> splits binary data according to user defined I<ranges> and renderes them as a B<hex> or/and B<decimal> 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<new> for all the possible options. Most option are also available from the command line utility I<hdr>.
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 <pre style ="font-family: monospace; background-color: #000 ;">
158 <span style = 'color:#fff; '>RANGE_NAME OFFSET CUMULATI HEX_DUMP ASCII_DUMP </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
159 </span><span style = 'color:#fff; '> 0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789012345 </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
160 </span><span style = 'color:#fff; color:#0f0; '>magic cookie </span><span style = 'color:#fff; color:#0f0; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000000</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000000</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0f0; '>0a 70 61 63 6b 61 67 65 20 44 61 74 </span><span style = 'color:#fff; color:#0f0; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0f0; '>.package Dat</span><span style = 'color:#fff; color:#0f0; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
161 </span><span style = 'color:#fff; color:#ff0; '></span><span style = 'color:#fff; color:#ff0; '>padding </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>0000000c</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>00000000</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '> </span><span style = 'color:#fff; color:#ff0; '>61 3a 3a 48 </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '> </span><span style = 'color:#fff; color:#ff0; '>a::H</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
162 </span><span style = 'color:#fff; color:#ff0; '>padding </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000010</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000004</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '>65 78 44 75 6d 70 3a 3a 52 61 6e 67 65 20 3b 0a </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '>exDump::Range ;.</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
163 </span><span style = 'color:#fff; color:#ff0; '>padding </span><span style = 'color:#fff; color:#ff0; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000020</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000014</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '>0a 75 73 65 20 73 74 72 69 63 74 3b </span><span style = 'color:#fff; color:#ff0; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '>.use strict;</span><span style = 'color:#fff; color:#ff0; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
164 </span><span style = 'color:#fff; color:#0ff; '></span><span style = 'color:#fff; color:#0ff; '>header </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>0000002c</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>00000000</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '> </span><span style = 'color:#fff; color:#0ff; '>0a 75 73 65 </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '> </span><span style = 'color:#fff; color:#0ff; '>.use</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
165 </span><span style = 'color:#fff; color:#0ff; '>header </span><span style = 'color:#fff; color:#0ff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000030</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000004</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '>20 </span><span style = 'color:#fff; color:#0ff; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '> </span><span style = 'color:#fff; color:#0ff; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
166 </span><span style = 'color:#fff; color:#f0f; '></span><span style = 'color:#fff; color:#f0f; '>data </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>00000031</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>00000000</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#f0f; '> </span><span style = 'color:#fff; color:#f0f; '>77 61 72 6e 69 6e 67 73 20 3b 0a 75 73 65 20 </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#f0f; '> </span><span style = 'color:#fff; color:#f0f; '>warnings ;.use </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
167 </span><span style = 'color:#fff; color:#f0f; '>data </span><span style = 'color:#fff; color:#f0f; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000040</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>0000000f</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#f0f; '>43 61 72 70 20 </span><span style = 'color:#fff; color:#f0f; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#f0f; '>Carp </span><span style = 'color:#fff; color:#f0f; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
168 </span><span style = 'color:#fff; color:#f00; '>&quot;extra data&quot;</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
169 </span><span style = 'color:#fff; color:#ff0; '></span><span style = 'color:#fff; color:#ff0; '>header </span><span style = 'color:#fff; color:#ff0; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>00000045</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>00000000</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '> </span><span style = 'color:#fff; color:#ff0; '>3b 0a 0a 42 45 </span><span style = 'color:#fff; color:#ff0; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '> </span><span style = 'color:#fff; color:#ff0; '>;..BE</span><span style = 'color:#fff; color:#ff0; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
170 </span><span style = 'color:#fff; color:#0ff; '></span><span style = 'color:#fff; color:#0ff; '>data </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>0000004a</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>00000000</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '> </span><span style = 'color:#fff; color:#0ff; '>47 49 4e 20 0a 7b </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '> </span><span style = 'color:#fff; color:#0ff; '>GIN .{</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
171 </span><span style = 'color:#fff; color:#0ff; '>data </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000050</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000006</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '>0a 0a 75 73 65 20 53 75 62 3a 3a 45 78 70 6f 72 </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '>..use Sub::Expor</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
172 </span><span style = 'color:#fff; color:#0ff; '>data </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000060</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000016</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '>74 65 72 20 2d 73 65 74 75 70 20 3d 3e 20 0a 09 </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '>ter -setup =&gt; ..</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
173 </span><span style = 'color:#fff; color:#0ff; '>data </span><span style = 'color:#fff; color:#0ff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000070</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000026</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '>7b 0a </span><span style = 'color:#fff; color:#0ff; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '>{.</span><span style = 'color:#fff; color:#0ff; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
174 </span><span style = 'color:#fff; color:#0f0; '></span><span style = 'color:#fff; color:#0f0; '>footer </span><span style = 'color:#fff; color:#0f0; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>00000072</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>00000000</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0f0; '> </span><span style = 'color:#fff; color:#0f0; '>09 65 78 70 </span><span style = 'color:#fff; color:#0f0; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0f0; '> </span><span style = 'color:#fff; color:#0f0; '>.exp</span><span style = 'color:#fff; color:#0f0; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
175 </span>
176 </pre>
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 <pre style ="font-family: monospace; background-color: #000 ;">
200  
201 <span style='color:#fff;'>OFFSET HEX_DUMP ASCII_DUMP RANGE_NAME </span>
202 <span style='color:#fff;'> 0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789012345 </span>
203 <span style='color:#fff;'>00000000</span><span style='color:#fff;'></span> <span style='color:#0f0;'>0a 70 61 63 6b 61 67 65 20 44 61 74 </span><span style='color:#ff0;'>61 3a 3a 48 </span> <span style='color:#0f0;'>.package Dat</span><span style='color:#ff0;'>a::H</span> <span style='color:#0f0;'>magic cookie</span><span style='color:#fff;'>, </span><span style='color:#ff0;'>padding</span><span style='color:#fff;'>, </span>
204 <span style='color:#fff;'>00000020</span> <span style='color:#ff0;'>65 78 44 75 6d 70 3a 3a 52 61 6e 67 65 20 3b 0a </span> <span style='color:#ff0;'>exDump::Range ;.</span> <span style='color:#ff0;'>padding</span><span style='color:#fff;'>, </span>
205 <span style='color:#fff;'>00000030</span><span style='color:#fff;'></span> <span style='color:#ff0;'>0a 75 73 65 20 73 74 72 69 63 74 3b </span><span style='color:#f0f;'>0a 75 73 65 </span> <span style='color:#ff0;'>.use strict;</span><span style='color:#f0f;'>.use</span> <span style='color:#ff0;'>padding</span><span style='color:#fff;'>, </span><span style='color:#f0f;'>header</span><span style='color:#fff;'>, </span>
206 <span style='color:#fff;'>00000050</span><span style='color:#fff;'></span> <span style='color:#f0f;'>20 </span><span style='color:#f00;'>77 61 72 6e 69 6e 67 73 20 3b 0a 75 73 65 20 </span> <span style='color:#f0f;'> </span><span style='color:#f00;'>warnings ;.use </span> <span style='color:#f0f;'>header</span><span style='color:#fff;'>, </span><span style='color:#f00;'>data</span><span style='color:#fff;'>, </span>
207 <span style='color:#fff;'>00000070</span><span style='color:#fff;'></span><span style='color:#fff;'></span> <span style='color:#f00;'>43 61 72 70 20 </span><span style='color:#0f0;'>3b 0a 0a 42 45 </span><span style='color:#ff0;'>47 49 4e 20 0a 7b </span> <span style='color:#f00;'>Carp </span><span style='color:#0f0;'>;..BE</span><span style='color:#ff0;'>GIN .{</span> <span style='color:#f00;'>data</span><span style='color:#fff;'>, </span><span style='color:#fff;'>"extra data"</span><span style='color:#fff;'>, </span><span style='color:#0f0;'>header</span><span style='color:#fff;'>, </span><span style='color:#ff0;'>data</span><span style='color:#fff;'>, </span>
208 <span style='color:#fff;'>000000a0</span> <span style='color:#ff0;'>0a 0a 75 73 65 20 53 75 62 3a 3a 45 78 70 6f 72 </span> <span style='color:#ff0;'>..use Sub::Expor</span> <span style='color:#ff0;'>data</span><span style='color:#fff;'>, </span>
209 <span style='color:#fff;'>000000b0</span> <span style='color:#ff0;'>74 65 72 20 2d 73 65 74 75 70 20 3d 3e 20 0a 09 </span> <span style='color:#ff0;'>ter -setup => ..</span> <span style='color:#ff0;'>data</span><span style='color:#fff;'>, </span>
210 <span style='color:#fff;'>000000c0</span><span style='color:#fff;'></span> <span style='color:#ff0;'>7b 0a </span><span style='color:#f0f;'>09 65 78 70 </span> <span style='color:#ff0;'>{.</span><span style='color:#f0f;'>.exp </span> <span style='color:#ff0;'>data</span><span style='color:#fff;'>, </span><span style='color:#f0f;'>footer</span><span style='color:#fff;'>, </span>
211  
212 </pre>
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<Dynamic range definition> below.
235  
236 You can also pass the ranges as a string. The L<hdr> 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<COLOR_NAMES> (see L<new>)
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<COLOR> in L<new>).
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<ff, fx, f0> are extracted form the data defined by the I<BITMAP> 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<x8b8> 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 <pre style ="font-family: monospace; background-color: #000 ;">
360 <span style = 'color:#fff; color:#0f0; '>header </span><span style = 'color:#fff; color:#0f0; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000000</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000000</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0f0; '>44 61 74 61 3a 3a 48 65 78 44 75 6d </span><span style = 'color:#fff; color:#0f0; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0f0; '>Data::HexDum</span><span style = 'color:#fff; color:#0f0; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
361 </span><span style = 'color:#fff; color:#ff0; '></span><span style = 'color:#fff; color:#ff0; '>BITMAP </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>0000000c</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>00000000</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '> </span><span style = 'color:#fff; color:#ff0; '>70 3a 3a 52 </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '> </span><span style = 'color:#fff; color:#ff0; '>p::R</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
362 </span><span style = 'color:#fff; color:#ff0; '>.ff </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '>02 .. 03</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '>-- -- -- 00 ----------------------------00-- </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '>.bitfield: ---. </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
363 </span><span style = 'color:#fff; color:#0ff; '>.fx </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '>00 .. 31</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '>70 3a 3a 52 01110000001110100011101001010010 </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '>.bitfield: p::R </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
364 </span><span style = 'color:#fff; color:#f0f; '>.f0 </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#f0f; '>00 .. 15</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#f0f; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#f0f; '>-- -- 3a 52 ----------------0011101001010010 </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#f0f; '>.bitfield: --:R </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
365 </span><span style = 'color:#fff; color:#f00; '>footer </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000010</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000000</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#f00; '>61 6e 67 65 0a 3d 3d 3d 3d 3d 3d 3d 3d 3d 3d 3d </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#f00; '>ange.===========</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
366 </span>
367 </pre>
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<Data::HexDump::Range>
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<hdr -r 'magic cookie, 5 :other,37 :bf,b8 :skip,X32,, I skipped :more, 20' -rul -col -o ver>
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 <pre style ="font-family: monospace; background-color: #000 ;">
398 <span style = 'color:#fff; '>RANGE_NAME OFFSET CUMULATI HEX_DUMP ASCII_DUMP </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
399 </span><span style = 'color:#fff; '> 0 1 2 3 4 5 6 7 8 9 a b c d e f 0123456789012345 </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
400 </span><span style = 'color:#fff; color:#0f0; '>magic cookie </span><span style = 'color:#fff; color:#0f0; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000000</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000000</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0f0; '>44 61 74 61 3a </span><span style = 'color:#fff; color:#0f0; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0f0; '>Data:</span><span style = 'color:#fff; color:#0f0; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
401 </span><span style = 'color:#fff; color:#ff0; '></span><span style = 'color:#fff; color:#ff0; '>other </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>00000005</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>00000000</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '> </span><span style = 'color:#fff; color:#ff0; '>3a 48 65 78 44 75 6d 70 3a 3a 52 </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '> </span><span style = 'color:#fff; color:#ff0; '>:HexDump::R</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
402 </span><span style = 'color:#fff; color:#ff0; '>other </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000010</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>0000000b</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '>61 6e 67 65 0a 3d 3d 3d 3d 3d 3d 3d 3d 3d 3d 3d </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '>ange.===========</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
403 </span><span style = 'color:#fff; color:#ff0; '>other </span><span style = 'color:#fff; color:#ff0; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000020</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>0000001b</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '>3d 3d 3d 3d 3d 3d 3d 3d 3d 0a </span><span style = 'color:#fff; color:#ff0; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#ff0; '>=========.</span><span style = 'color:#fff; color:#ff0; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
404 </span><span style = 'color:#fff; color:#0ff; '>.bf </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '>00 .. 07</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '>-- -- -- 0a ------------------------00001010 </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#0ff; '>.bitfield: ---. </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
405 </span><span style = 'color:#fff; color:#f0f; '>&gt;&gt;skip </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>0000002a</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000049</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#f0f; '>00 00 00 20 bytes skipped </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#f0f; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
406 </span><span style = 'color:#fff; color:#f00; '></span><span style = 'color:#fff; color:#f00; '>more </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>0000004a</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '></span><span style = 'color:#fff; '>00000000</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#f00; '> </span><span style = 'color:#fff; color:#f00; '>20 63 6f 6c 6f 72 </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#f00; '> </span><span style = 'color:#fff; color:#f00; '> color</span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
407 </span><span style = 'color:#fff; color:#f00; '>more </span><span style = 'color:#fff; color:#f00; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000050</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>00000006</span><span style = 'color:#fff; '></span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#f00; '>2c 20 62 69 74 66 69 65 6c 64 73 20 61 6e </span><span style = 'color:#fff; color:#f00; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; color:#f00; '>, bitfields an</span><span style = 'color:#fff; color:#f00; '> </span><span style = 'color:#fff; '> </span><span style = 'color:#fff; '>
408 </span>
409 </pre>
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<Arguments> - See L<gather>
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<dump> method
472  
473 =item * $offset - Integer - current offset in $data
474  
475 =back
476  
477 I<Returns> -
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<Note> this is, very, different from L<User defined range generator> 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<undef>.
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<Arguments> - See L<gather>
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<dump> method
527  
528 =item * $offset - Integer - current offset in $data
529  
530 =back
531  
532 I<Returns> -
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<hdr_examples.pod> in the distribution.
549  
550 =head1 SUBROUTINES/METHODS
551  
552 =cut
553  
554 #-------------------------------------------------------------------------------
555  
556 sub new
557 3 ▶{
Subroutine new: called CC=3 SCAR=11.0
Pod documented
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<Arguments> - 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<false>
599  
600 =item * DUMP_ORIGINAL_RANGE_DESCRIPTION - Boolean - Diplays the un-processed range descritption.
601  
602 With B<DUMP_RANGE_DESCRIPTION>, 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<ANSI> 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<false>
660  
661 =item * DISPLAY_RULER - Boolean - if set, a ruler is displayed above the dump, Default is I<false>
662  
663 =item * DISPLAY_OFFSET - Boolean - If set, the offset column is displayed. Default I<true>
664  
665 =item * DISPLAY_CUMULATIVE_OFFSET - Boolean - If set, the cumulative offset column is displayed in 'vertical' rendering mode. Default is I<true>
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<true>
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<true>
672  
673 =item * DISPLAY_COMMENT_RANGE - Boolean - if set, comment ranges are displayed. default is I<true>
674  
675 =item * DISPLAY_RANGE_SIZE - Bolean - if set the range size is prepended to the name. Default I<false>
676  
677 =item * DISPLAY_ASCII_DUMP - Boolean - If set, the ASCII representation of the binary data is displayed. Default is I<true>
678  
679 =item * DISPLAY_HEX_DUMP - Boolean - If set, the hexadecimal dump column is displayed. Default is I<true>
680  
681 =item * DISPLAY_HEXASCII_DUMP - Boolean - If set, the comined hexadecimal and ASCII dump column is displayed. Default is I<false>
682  
683 =item * DISPLAY_DEC_DUMP - Boolean - If set, the decimall dump column is displayed. Default is I<false>
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<false>
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<Returns> - Nothing
718  
719 I<Exceptions> - Dies if an unsupported option is passed.
720  
721 =cut
722  
723 3 my ($invocant, @setup_data) = @_ ;
724  
725 3 ▶my $class = ref($invocant) || $invocant ;
Condition100%3/3
ref $invocant || $invocant
l!l&&r!l&&!r
111
MC/DC100%2/2
ref $invocant || $invocant
ref $invocant $invocant
Truth table100%3/3
A || B
A= ref $invocantB= $invocant
ABresult
1X1
011
000
726 3 ▶confess 'Error: Invalid constructor call' unless defined $class ;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $class 1 2 3
727  
728 2 my $object = {} ;
729  
730 2 my ($package, $file_name, $line) = caller() ;
731 2 bless $object, $class ;
732  
733 2 $object->Setup($package, $file_name, $line, @setup_data) ;
734  
735 2 return($object) ;
736 }
737  
738 #-------------------------------------------------------------------------------
739  
740 sub gather
741 0 ▶{
Subroutine gather: not called CC=1 SCAR=6.9
Pod documented
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<Arguments>
754  
755 =over 2
756  
757 =item * $range_description - See L<Range definition>
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<Returns> - An integer - the number of processed bytes
782  
783 I<Exceptions> - See L<_gather>
784  
785 =cut
786  
787 0 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 0 ▶{
Subroutine dump_gathered: not called CC=1 SCAR=6.9
Pod documented
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<Arguments> - None
809  
810 I<Returns> - A string - the binary data formated according to the rnage descriptions
811  
812 I<Exceptions> - None
813  
814 =cut
815  
816 0 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 0 ▶{
Subroutine dump: not called CC=2 SCAR=17.9
Pod documented
829  
830 =head2 dump($range_description, $data, $offset, $size)
831  
832 Dump the data, up to $size, according to the description
833  
834 I<Arguments> - See L<gather>
835  
836 I<Returns> - A string - the formated dump
837  
838 I<Exceptions> - dies if the range description is invalid
839  
840 =cut
841  
842 0 my ($self, $range_description, $data, $offset, $size) = @_ ;
843  
844 0 ▶return unless defined wantarray ;
Branch: 1 branch
BranchTrueFalseTotal
unless defined wantarray 0 0 0
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 0 ▶{
Subroutine get_dump_and_consumed_data_size: not called CC=2 SCAR=17.9
Pod documented
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<Arguments> - See L<gather>
867  
868 I<Returns> -
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<Exceptions> - dies if the range description is invalid
879  
880 =cut
881  
882 0 my ($self,$data, $offset, $size) = @_ ;
883  
884 0 ▶return unless defined wantarray ;
Branch: 1 branch
BranchTrueFalseTotal
unless defined wantarray 0 0 0
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 0 ▶{
Subroutine reset: not called CC=1 SCAR=6.9
Pod documented
897  
898 =head2 reset()
899  
900 Clear the gathered dump
901  
902 I<Arguments> - None
903  
904 I<Returns> - Nothing
905  
906 I<Exceptions> - None
907  
908 =cut
909  
910 0 my ($self) = @_ ;
911  
912 0 $self->{GATHERED} = [] ;
913  
914 0 return ;
915 }
916  
917 #-------------------------------------------------------------------------------
918  
919 2 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<http://annocpan.org/dist/Data-HexDump-Range>
961  
962 =item * RT: CPAN's request tracker
963  
964 Please report any bugs or feature requests to L <bug-data-hexdump-range@rt.cpan.org>.
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<http://search.cpan.org/dist/Data-HexDump-Range>
972  
973 =back
974  
975 =head1 SEE ALSO
976  
977 L<Data::Hexdumper>, L<Data::ParseBinary>, L<Convert::Binary::C>, L<Parse::Binary>
978  
979 =cut
« Range/Format.pm ↑ Summary